[WIP] Sourcegraph Kustomize

WIP - DO NOT USE

This repository contains a set of Kustomize components and overlays that are designed to work with the Sourcegraph Kubernetes deployment repository, and to replace the older version of the overlays.

The new set of Kustomize components and overlays provide more flexibility in creating an overlay that suits your deployments and eliminates the need to clone the deployment repository.

IMPORTANT: Only works with Sourcegraph version TBA

Kustomize

Kustomize is built into kubectl in version >= 1.14.

Install Kustomize: https://kubectl.docs.kubernetes.io/installation/kustomize/

Overlays

An overlay specifies customizations for a base directory of Kubernetes manifests, in this case the base/ directory in the deploy-sourcegraph repository.

Each overlay is created with different kustomize components that are located inside the components directory.

Components

A kustomize component is essentially a smaller unit of a normal kustomization, and designed to be reusable. They are evaluated after the resources of the parent kustomization (overlay or component) have been accumulated, and on top of them. (source)

To understand what an overlay does is to check what components the overlay is using. The components are listed under the components field inside the kustomization.yaml file of an overlay.

How to use

There are two ways to use any of our overlays:

1. Remote build
2. Local build

Option 1: Remote build

You can create an overlay to deploy Sourcegraph without cloning the reference repository by using remote build.

Build an overlay

All you need is to copy the files located inside the directory for the overlay you would like to use, for example, make a copy of all the files inside ./overlays/replicas to use the replica overlay, and then run the following command from the root of the overlay directory where the kustomization.yaml file is located to produce an output file called .output.yaml that contains all the manifests generated by the overlay:

# When using kustomize:
$ kustomize build . -o .output.yaml
# When using kubectl:
$ kubectl apply -k . > .output.yaml

Apply an overlay

Once you have confirmed the output is correct, you can start the deploying process by run the following command:

# When using kustomize:
$ kustomize build . | kubectl apply -f -
# When using kubectl:
$ kubectl apply -k .

Option 2: Local build

If none of the provided overlays fit your needs, or additional changes and customizations are required, then you will need to clone this repository and follow the recommended instructions below.

Create a new component

If you want to modify an existing component, it is recommended to create a new component instead and make the changes inside the new component. Making changes directly to the existing components are not recommended as it can cause merge conflicts in the future.

Here is an example of a new overlay that is using a new component that does not exist remotely, while still using our deployment repository as base remotely:

# kustomization.yaml for the new overlay
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: ns-sourcegraph-example
resources:
  - https://github.com/sourcegraph/deploy-sourcegraph/base?ref=v4.3.0
components:
  # local path to the new component you created within the ./components folder
  - ../../components/your-new-component
  #   You can also refer to other sourcegraph component that is hosted in other remote repository
  - https://github.com/org/repo/path/to/new/component

Create a new overlay

Here is an example of what a typical kustomization.yaml file that is use to build a Kustomize overlay looks like:

# NOTE: this is the kustomization.yaml for our non-privileged overlay
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: ns-sourcegraph-example
resources:
  - https://github.com/sourcegraph/deploy-sourcegraph/base?ref=bee/kustomize
components:
  - https://github.com/sourcegraph/kustomize/components/delete-cadvisor
  - https://github.com/sourcegraph/kustomize/components/non-privileged
  - https://github.com/sourcegraph/kustomize/components/non-privileged-create-cluster

This example overlay that has the following features:

• use the manifests defined in the branch called bee/kustomize located inside the github.com/sourcegraph/deploy-sourcegraph repository, and
• apply the delete-cadvisor component
• apply the non-privileged component
• apply the non-privileged-create-cluster component

If you need to add additional component to this overlay, like changing the service type to NodePort for example, you can create a new overlay folder with the files from the non-privileged overlay, and then add the serviceType/NodePort component under components.

# kustomization.yaml for the new overlay
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: ns-sourcegraph-example
resources:
  - https://github.com/sourcegraph/deploy-sourcegraph/base?ref=bee/kustomize
components:
  - https://github.com/sourcegraph/kustomize/components/delete-cadvisor
  - https://github.com/sourcegraph/kustomize/components/non-privileged
  - https://github.com/sourcegraph/kustomize/components/non-privileged-create-cluster
  - https://github.com/sourcegraph/kustomize/components/serviceType/NodePort

Build an overlay

This allows you to preview the output files of your overlay before applying them to your cluster.

Run the following command in the root of this repository. Replace $OVERLAY with the name of the overlay.

Individual output file

To produce a seperated manifest file for each resources to the overlays/.preview/ directory:

When using kustomize:

# example: kustomize build overlays/minikube > overlays/.preview/
$ kustomize build overlays/$OVERLAY > overlays/.preview/

When using kubectl:

# example: kubectl apply -k overlays/minikube > overlays/.preview/
$ kubectl apply -k overlays/$OVERLAY > overlays/.preview/

Single output file

To groups all the manifests into a single file named output.yaml inside the overlays/.preview/ directory:

When using kustomize:

# example: kustomize build overlays/minikube > overlays/.preview/output.yaml
$ kustomize build overlays/$OVERLAY > overlays/.preview/output.yaml

When using kubectl:

# example: kubectl apply -k overlays/minikube > overlays/.preview/output.yaml
$ kubectl apply -k overlays/$OVERLAY > overlays/.preview/output.yaml

Apply an overlay

To apply the customizations configured with your overlay:

Run the following command in the root of this repository. Replace $OVERLAY with the name of the overlay.

When using kustomize:

# example: kustomize build overlays/minikube | kubectl apply -f -
kustomize build overlays/$OVERLAY | kubectl apply -f -

When using kubectl:

# example: kubectl apply -k overlays/minikube
kubectl apply -k overlays/$OVERLAY