diff --git a/website/content/en/docs/building-operators/helm/migration.md b/website/content/en/docs/building-operators/helm/migration.md index 6bd985ca9f..bec18b203d 100644 --- a/website/content/en/docs/building-operators/helm/migration.md +++ b/website/content/en/docs/building-operators/helm/migration.md @@ -58,28 +58,83 @@ $ cd nginx-operator $ operator-sdk init --plugins=helm --domain=example.com ``` -Now that we have our new project initialized, we need to re-create each of our APIs. +Now that we have our new project initialized, we need to re-create each of our APIs. Using our API example from earlier (`cache.example.com`), we'll use `cache` for the `--group` flag. +For `--version` and `--kind`, we use `spec.versions[0].name` and `spec.names.kind`, respectively. + For each API in the existing project, run: ```sh $ operator-sdk create api \ --group=cache \ - --api-version= \ + --version= \ --kind= \ --helm-chart=/helm-charts/ ``` -**Note** Ensure that you use the same values for the flags to recreate the same Helm Chart and API's. If you have -more than one chart or API's you can add them via `operator-sdk create api` command. For further information check the [quick-start][quickstart]. - -### Replacing the content +Now that we have our new project initialized, we need to re-create each of our APIs. +Using our API example from earlier (`cache.example.com`), we'll use `cache` for the +`--group` flag. + +For `--version` and `--kind`, we use `spec.versions[0].name` and `spec.names.kind`, respectively. + +### Migrating your Custom Resource samples + +Update the CR manifests in `config/samples` with the values of the CRs in your existing project which are in `deploy/crds/___cr.yaml` + +### Migrating `watches.yaml` + +Check if you have custom options in the `watches.yaml` file of your existing project. If so, update the new `watches.yaml` file to match. In our example, it will look like: + +```yaml +# Use the 'create api' subcommand to add watches to this file. +- group: example.com + version: v1alpha1 + kind: Nginx + chart: helm-charts/nginx +# +kubebuilder:scaffold:watch +``` + +**NOTE**: Do not remove the `+kubebuilder:scaffold:watch` [marker][marker]. It allows the tool to update the watches file when new APIs are created. + +### Checking the Permissions (RBAC) + +In your new project, roles are automatically generated in `config/rbac/role.yaml`. +If you modified these permissions manually in `deploy/role.yaml` in your existing +project, you need to re-apply them in `config/rbac/role.yaml`. + +New projects are configured to watch all namespaces by default, so they need a `ClusterRole` to have the necessary permissions. Ensure that `config/rbac/role.yaml` remains a `ClusterRole` if you want to retain the default behavior of the new project conventions. For further information refer to the [operator scope][operator-scope] documentation. + +The following rules were used in earlier versions of helm-operator to automatically create and manage services and servicemonitors for metrics collection. If your operator's charts don't require these rules, they can safely be left out of the new `config/rbac/role.yaml` file: + +``` + - apiGroups: + - monitoring.coreos.com + resources: + - servicemonitors + verbs: + - get + - create + - apiGroups: + - apps + resourceNames: + - memcached-operator + resources: + - deployments/finalizers + verbs: + - update +``` + +### Configuring your Operator + +If your existing project has customizations in `deploy/operator.yaml`, they need to be ported to +`config/manager/manager.yaml`. If you are passing custom arguments in your deployment, make sure to also update `config/default/auth_proxy_patch.yaml`. + +Note that the following environment variables are no longer used. -- Update the CR manifests in `config/samples` with the values of the CR's in your old project which are in `deploy/crds/` -- Check if you have customizations options in the `watch.yaml` file of your previous project and then, update the new `watch.yaml` file with the same ones -- Ensure that all roles configured in the `/deploy/roles.yaml` will be applied in the new project in the file `config/rbac/role.yaml` -- If you have customizations in your `helm-charts` then, apply them in the new `helm-charts`. Note that this directory was not changed at all. +- `OPERATOR_NAME` is deprecated. It is used to define the name for a leader election config map. Operator authors should begin using `--leader-election-id` instead. +- `POD_NAME` was used to enable a particular pod to hold the leader election lock when the Helm operator used the leader for life mechanism. Helm operator now uses controller-runtime's leader with lease mechanism, and `POD_NAME` is no longer necessary. ## Exporting metrics @@ -88,14 +143,15 @@ it in the `config/default/kustomization.yaml`. Please see the [metrics][metrics] The default port used by the metric endpoint binds to was changed from `:8383` to `:8080`. To continue using port `8383`, specify `--metrics-addr=:8383` when you start the operator. -### Checking the changes +## Checking the changes -Now, follow the steps in the section [Build and run the operator][build-run-quick] to verify your project is running. +Finally, follow the steps in the section [Build and run the operator][build-and-run-the-operator] to verify your project is running. [quickstart-legacy]: https://v0-19-x.sdk.operatorframework.io/docs/helm/quickstart/ [quickstart]: /docs/building-operators/helm/quickstart [integration-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/integrating-kubebuilder-and-osdk.md -[build-run-quick]: /docs/building-operators/helm/quickstart#build-and-run-the-operator +[build-and-run-the-operator]: /docs/building-operators/helm/tutorial#build-and-run-the-operator [kustomize]: https://github.com/kubernetes-sigs/kustomize [kube-auth-proxy]: https://github.com/brancz/kube-rbac-proxy [metrics]: https://book.kubebuilder.io/reference/metrics.html?highlight=metr#metrics +[marker]: https://book.kubebuilder.io/reference/markers.html?highlight=markers#marker-syntax \ No newline at end of file diff --git a/website/content/en/docs/building-operators/helm/quickstart.md b/website/content/en/docs/building-operators/helm/quickstart.md index 66d82bc602..2629cc223b 100644 --- a/website/content/en/docs/building-operators/helm/quickstart.md +++ b/website/content/en/docs/building-operators/helm/quickstart.md @@ -7,324 +7,86 @@ description: A simple set of instructions that demonstrates the basics of settin This guide walks through an example of building a simple nginx-operator powered by [Helm][helm-official] using tools and libraries provided by the Operator SDK. -**Note**: This guide uses [minikube][minikube-tool] version v0.25.0+ as the -local Kubernetes cluster and [quay.io][quay-link] for the public registry. +## Prerequisites -[minikube-tool]:https://github.com/kubernetes/minikube#installation -[quay-link]:https://quay.io +- [Install `operator-sdk`][operator_install] and its prequisites. +- Access to a Kubernetes v1.16.0+ cluster. -## Create a new project +## Quickstart Steps -Use the CLI to create a new Helm-based nginx-operator project: +### Create a project -```sh -$ mkdir nginx-operator -$ cd nginx-operator -$ operator-sdk init --plugins=helm --domain=com --group=example --version=v1alpha1 --kind=Nginx -``` - -This creates the nginx-operator project specifically for watching the -Nginx resource with APIVersion `example.com/v1alpha1` and Kind -`Nginx`. - -For Helm-based projects, `operator-sdk init` also generates the RBAC rules -in `config/rbac/role.yaml` based on the resources that would be deployed by the -chart's default manifest. Be sure to double check that the rules generated -in `config/rbac/role.yaml` meet the operator's permission requirements. - -To learn more about the project directory structure, see the -[project layout][layout-doc] doc. - -### Use an existing chart - -Instead of creating your project with a boilerplate Helm chart, you can also use `--helm-chart`, `--helm-chart-repo`, and `--helm-chart-version` to use an existing chart, either from your local filesystem or a remote chart repository. - -If `--helm-chart` is specified, the `--group`, `--version`, and `--kind` flags become optional. If left unset, the default will be: - -| Flag | Value | -| :--- | :--- | -| domain | my.domain | -| group | charts | -| kind | deduce from the specified chart | -| version | v1alpha1 | - -If `--helm-chart` is a local chart archive (e.g `example-chart-1.2.0.tgz`) or directory, -it will be validated and unpacked or copied into the project. - -Otherwise, the SDK will attempt to fetch the specified helm chart from a remote repository. - -If a custom repository URL is not specified by `--helm-chart-repo`, the following chart reference formats are supported: - -- `/`: Fetch the helm chart named `chartName` from the helm - chart repository named `repoName`, as specified in the - `$HELM_HOME/repositories/repositories.yaml` file. - Use [`helm repo add`](https://helm.sh/docs/helm/helm_repo_add) to configure this file. - -- ``: Fetch the helm chart archive at the specified URL. - -If a custom repository URL is specified by `--helm-chart-repo`, the only supported format for `--helm-chart` is: - -- ``: Fetch the helm chart named `chartName` in the helm chart repository - specified by the `--helm-chart-repo` URL. - -If `--helm-chart-version` is not set, the SDK will fetch the latest available version of the helm chart. Otherwise, it will fetch the specified version. The option `--helm-chart-version` is not used when `--helm-chart` itself refers to a specific version, for example when it is a local path or a URL. - -**Note:** For more details and examples run `operator-sdk init --plugins=helm --help`. - -### Operator scope - -Read the [operator scope][operator-scope] documentation on how to run your operator as namespace-scoped vs cluster-scoped. - - -## Customize the operator logic - -For this example the nginx-operator will execute the following -reconciliation logic for each `Nginx` Custom Resource (CR): - -- Create a nginx Deployment if it doesn't exist -- Create a nginx Service if it doesn't exist -- Create a nginx Ingress if it is enabled and doesn't exist -- Ensure that the Deployment, Service, and optional Ingress match the desired configuration (e.g. replica count, image, service type, etc) as specified by the `Nginx` CR - -### Watch the Nginx CR - -By default, the nginx-operator watches `Nginx` resource events as shown -in `watches.yaml` and executes Helm releases using the specified chart: - -```yaml -# Use the 'create api' subcommand to add watches to this file. -- group: example.com - version: v1alpha1 - kind: Nginx - chart: helm-charts/nginx -# +kubebuilder:scaffold:watch -``` - -### Reviewing the Nginx Helm Chart - -When a Helm operator project is created, the SDK creates an example Helm chart -that contains a set of templates for a simple Nginx release. - -For this example, we have templates for deployment, service, and ingress -resources, along with a `NOTES.txt` template, which Helm chart developers use -to convey helpful information about a release. - -If you aren't already familiar with Helm Charts, take a moment to review -the [Helm Chart developer documentation][helm-charts]. - -### Understanding the Nginx CR spec - -Helm uses a concept called [values][helm-values] to provide customizations -to a Helm chart's defaults, which are defined in the Helm chart's `values.yaml` -file. - -Overriding these defaults is as simple as setting the desired values in the CR -spec. Let's use the number of replicas as an example. - -First, inspecting `helm-charts/nginx/values.yaml`, we see that the chart has a -value called `replicaCount` and it is set to `1` by default. If we want to have -2 nginx instances in our deployment, we would need to make sure our CR spec -contained `replicaCount: 2`. - -Update `config/samples/example_v1alpha1_nginx.yaml` to look like the following: - -```yaml -apiVersion: example.com/v1alpha1 -kind: Nginx -metadata: - name: nginx-sample -spec: - replicaCount: 2 -``` - -Similarly, we see that the default service port is set to `80`, but we would -like to use `8080`, so we'll again update `config/samples/example_v1alpha1_nginx.yaml` -by adding the service port override: - -```yaml -apiVersion: example.com/v1alpha1 -kind: Nginx -metadata: - name: example-nginx -spec: - replicaCount: 2 - service: - port: 8080 -``` - -As you may have noticed, the Helm operator simply applies the entire spec as if -it was the contents of a values file, just like `helm install -f ./overrides.yaml` -works. - -## Build and run the operator - -Before running the operator, Kubernetes needs to know about the new custom -resource definition the operator will be watching. - -Deploy the CRD: +Create and change into a directory for your project. Then call `operator-sdk init` +with the Helm plugin to initialize the [base project layout][project_layout]: ```sh -make install +mkdir nginx-operator +cd nginx-operator +operator-sdk init --plugins=helm ``` -Once this is done, there are two ways to run the operator: - -- As a pod inside a Kubernetes cluster -- As a go program outside the cluster using `operator-sdk` +### Create an API -### 1. Run as a pod inside a Kubernetes cluster - -Running as a pod inside a Kubernetes cluster is preferred for production use. - -Build the nginx-operator image and push it to a registry: +Create a simple nginx API using Helm's built-in chart boilerplate (from +`helm create`): ```sh -export IMG=quay.io/example/nginx-operator:v0.0.1 -make docker-build docker-push IMG=$IMG +operator-sdk create api --group demo --version v1 --kind Nginx ``` -**Note:** Kubernetes deployment manifests are generated in `config/manager/manager.yaml`. - -Deploy the nginx-operator: +### Build and push the operator image -```sh -make deploy IMG=$IMG -``` - -Verify that the nginx-operator is up and running: +Use the built-in Makefile targets to build and push your operator. Make +sure to define `IMG` when you call `make`: ```sh -$ kubectl get deployment -n nginx-operator-system -NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE -nginx-operator-controller-manager 1/1 1 1 1 77s +make docker-build docker-push IMG=/:tag ``` -### 2. Run outside the cluster +**NOTE**: To allow the cluster pull the image the repository needs to be + set as public or you must configure an image pull secret. -This method is preferred during the development cycle to speed up deployment and testing. -Run the operator locally with the default Kubernetes config file present at -`$HOME/.kube/config`: - -```sh -$ make run -INFO[0000] Go Version: go1.10.3 -INFO[0000] Go OS/Arch: linux/amd64 -INFO[0000] operator-sdk Version: v0.1.1+git -``` - -Run the operator locally with a provided Kubernetes config file: - -```sh -$ operator-sdk run local --kubeconfig= -INFO[0000] Go Version: go1.10.3 -INFO[0000] Go OS/Arch: linux/amd64 -INFO[0000] operator-sdk Version: v0.2.0+git -``` - -### 3. Deploy your Operator with the Operator Lifecycle Manager (OLM) - -OLM will manage creation of most if not all resources required to run your operator, -using a bit of setup from other `operator-sdk` commands. Check out the OLM integration -[user guide][quickstart-bundle] for more information. - -## Deploy the Nginx custom resource - -Apply the nginx CR that we modified earlier: - -```sh -$ kubectl apply -f config/samples/example_v1alpha1_nginx.yaml -``` +### Run the operator -Ensure that the nginx-operator creates the deployment for the CR: +Install the CRD and deploy the project to the cluster. Set `IMG` with +`make deploy` to use the image you just pushed: ```sh -$ kubectl get deployment -NAME READY UP-TO-DATE AVAILABLE AGE -nginx-sample 2/2 2 2 2m13s -``` - -Check the pods to confirm 2 replicas were created: - -```sh -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -nginx-sample-c786bfdcf-4g6md 1/1 Running 0 81s -nginx-sample-c786bfdcf-6bhmx 1/1 Running 0 81s - -Check that the service port is set to `8080`: - -```sh -$ kubectl get service -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -nginx-sample ClusterIP 10.96.26.3 8080/TCP 1m -``` - -### Update the replicaCount and remove the port - -Change the `spec.replicaCount` field from 2 to 3, remove the `spec.service` -field: - -```sh -$ cat config/samples/example_v1alpha1_nginx.yaml -apiVersion: example.com/v1alpha1 -kind: Nginx -metadata: - name: nginx-sample -spec: - replicaCount: 3 -``` - -And apply the change: -```sh -$ kubectl apply -f config/samples/example_v1alpha1_nginx.yaml +make install +make deploy IMG=/:tag ``` -Confirm that the operator changes the deployment size: +### Create a sample custom resource +Create a sample CR: ```sh -$ kubectl get deployment -NAME DESIRED CURRENT UP-TO-DATE AGE -nginx-sample 3/3 3 3 7m29s +kubectl apply -f config/samples/demo_v1_nginx.yaml ``` -Check that the service port is set to the default (`80`): - +Watch for the CR to trigger the operator to deploy the nginx deployment +and service: ```sh -$ kubectl get service -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -nginx-sample ClusterIP 10.96.152.76 80/TCP 7m54s +kubectl get all -l "app.kubernetes.io/instance=nginx-sample" ``` -### Troubleshooting - -Use the following command to check the operator logs. +### Clean up +Delete the CR to uninstall the release: ```sh -$ kubectl logs deployment.apps/nginx-operator-controller-manager -n nginx-operator-system -c manager +kubectl delete -f config/samples/demo_v1_nginx.yaml ``` -Use the following command to check the CR status and events. - +Use `make undeploy` to uninstall the operator and its CRDs: ```sh -$ kubectl describe nginxes.example.com +make undeploy ``` -### Cleanup - -Clean up the resources: +## Next Steps -```sh -$ kubectl delete -f config/samples/example_v1alpha1_nginx.yaml -$ make undeploy -``` -**NOTE** Additional CR/CRD's can be added to the project by running, for example, the command :`operator-sdk create api --group=example --version=v1alpha1 --kind=AppService` +Read the [tutorial][tutorial] for an in-depth walkthough of building a Helm operator. - -[operator-scope]: /docs/building-operators/golang/operator-scope -[layout-doc]: /docs/building-operators/helm/reference/project_layout/ -[helm-charts]:https://helm.sh/docs/topics/charts/ -[helm-values]:https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing -[helm-official]:https://helm.sh/docs/ +[operator_install]: /docs/installation/install-operator-sdk +[project_layout]: /docs/building-operators/helm/reference/project_layout/ +[tutorial]: /docs/building-operators/helm/tutorial/ +[helm-official]: https://helm.sh/docs/ diff --git a/website/content/en/docs/building-operators/helm/tutorial.md b/website/content/en/docs/building-operators/helm/tutorial.md new file mode 100644 index 0000000000..531c228220 --- /dev/null +++ b/website/content/en/docs/building-operators/helm/tutorial.md @@ -0,0 +1,330 @@ +--- +title: Tutorial for Helm-based Operators +linkTitle: Tutorial +weight: 200 +description: A simple set of instructions that demonstrates the basics of setting up and running a Helm-based operator. +--- + +This guide walks through an example of building a simple nginx-operator powered by [Helm][helm-official] using tools and libraries provided by the Operator SDK. + +**Note**: This guide uses [minikube][minikube-tool] version v0.25.0+ as the +local Kubernetes cluster and [quay.io][quay-link] for the public registry. + +[minikube-tool]:https://github.com/kubernetes/minikube#installation +[quay-link]:https://quay.io + +## Create a new project + +Use the CLI to create a new Helm-based nginx-operator project: + +```sh +$ mkdir nginx-operator +$ cd nginx-operator +$ operator-sdk init --plugins=helm --domain=com --group=example --version=v1alpha1 --kind=Nginx +``` + +This creates the nginx-operator project specifically for watching the +Nginx resource with APIVersion `example.com/v1alpha1` and Kind +`Nginx`. + +For Helm-based projects, `operator-sdk init` also generates the RBAC rules +in `config/rbac/role.yaml` based on the resources that would be deployed by the +chart's default manifest. Be sure to double check that the rules generated +in `config/rbac/role.yaml` meet the operator's permission requirements. + +To learn more about the project directory structure, see the +[project layout][layout-doc] doc. + +### Use an existing chart + +Instead of creating your project with a boilerplate Helm chart, you can also use `--helm-chart`, `--helm-chart-repo`, and `--helm-chart-version` to use an existing chart, either from your local filesystem or a remote chart repository. + +If `--helm-chart` is specified, the `--group`, `--version`, and `--kind` flags become optional. If left unset, the default will be: + +| Flag | Value | +| :--- | :--- | +| domain | my.domain | +| group | charts | +| kind | deduce from the specified chart | +| version | v1alpha1 | + +If `--helm-chart` is a local chart archive (e.g `example-chart-1.2.0.tgz`) or directory, +it will be validated and unpacked or copied into the project. + +Otherwise, the SDK will attempt to fetch the specified helm chart from a remote repository. + +If a custom repository URL is not specified by `--helm-chart-repo`, the following chart reference formats are supported: + +- `/`: Fetch the helm chart named `chartName` from the helm + chart repository named `repoName`, as specified in the + `$HELM_HOME/repositories/repositories.yaml` file. + Use [`helm repo add`](https://helm.sh/docs/helm/helm_repo_add) to configure this file. + +- ``: Fetch the helm chart archive at the specified URL. + +If a custom repository URL is specified by `--helm-chart-repo`, the only supported format for `--helm-chart` is: + +- ``: Fetch the helm chart named `chartName` in the helm chart repository + specified by the `--helm-chart-repo` URL. + +If `--helm-chart-version` is not set, the SDK will fetch the latest available version of the helm chart. Otherwise, it will fetch the specified version. The option `--helm-chart-version` is not used when `--helm-chart` itself refers to a specific version, for example when it is a local path or a URL. + +**Note:** For more details and examples run `operator-sdk init --plugins=helm --help`. + +### Operator scope + +Read the [operator scope][operator-scope] documentation on how to run your operator as namespace-scoped vs cluster-scoped. + + +## Customize the operator logic + +For this example the nginx-operator will execute the following +reconciliation logic for each `Nginx` Custom Resource (CR): + +- Create a nginx Deployment if it doesn't exist +- Create a nginx Service if it doesn't exist +- Create a nginx Ingress if it is enabled and doesn't exist +- Ensure that the Deployment, Service, and optional Ingress match the desired configuration (e.g. replica count, image, service type, etc) as specified by the `Nginx` CR + +### Watch the Nginx CR + +By default, the nginx-operator watches `Nginx` resource events as shown +in `watches.yaml` and executes Helm releases using the specified chart: + +```yaml +# Use the 'create api' subcommand to add watches to this file. +- group: example.com + version: v1alpha1 + kind: Nginx + chart: helm-charts/nginx +# +kubebuilder:scaffold:watch +``` + +### Reviewing the Nginx Helm Chart + +When a Helm operator project is created, the SDK creates an example Helm chart +that contains a set of templates for a simple Nginx release. + +For this example, we have templates for deployment, service, and ingress +resources, along with a `NOTES.txt` template, which Helm chart developers use +to convey helpful information about a release. + +If you aren't already familiar with Helm Charts, take a moment to review +the [Helm Chart developer documentation][helm-charts]. + +### Understanding the Nginx CR spec + +Helm uses a concept called [values][helm-values] to provide customizations +to a Helm chart's defaults, which are defined in the Helm chart's `values.yaml` +file. + +Overriding these defaults is as simple as setting the desired values in the CR +spec. Let's use the number of replicas as an example. + +First, inspecting `helm-charts/nginx/values.yaml`, we see that the chart has a +value called `replicaCount` and it is set to `1` by default. If we want to have +2 nginx instances in our deployment, we would need to make sure our CR spec +contained `replicaCount: 2`. + +Update `config/samples/example_v1alpha1_nginx.yaml` to look like the following: + +```yaml +apiVersion: example.com/v1alpha1 +kind: Nginx +metadata: + name: nginx-sample +spec: + replicaCount: 2 +``` + +Similarly, we see that the default service port is set to `80`, but we would +like to use `8080`, so we'll again update `config/samples/example_v1alpha1_nginx.yaml` +by adding the service port override: + +```yaml +apiVersion: example.com/v1alpha1 +kind: Nginx +metadata: + name: nginx-sample +spec: + replicaCount: 2 + service: + port: 8080 +``` + +As you may have noticed, the Helm operator simply applies the entire spec as if +it was the contents of a values file, just like `helm install -f ./overrides.yaml` +works. + +## Build and run the operator + +Before running the operator, Kubernetes needs to know about the new custom +resource definition the operator will be watching. + +Deploy the CRD: + +```sh +make install +``` + +Once this is done, there are two ways to run the operator: + +- As a pod inside a Kubernetes cluster +- As a go program outside the cluster using `operator-sdk` + +### 1. Run as a pod inside a Kubernetes cluster + +Running as a pod inside a Kubernetes cluster is preferred for production use. + +Build the nginx-operator image and push it to a registry: + +```sh +export IMG=quay.io/example/nginx-operator:v0.0.1 +make docker-build docker-push IMG=$IMG +``` + +**Note:** Kubernetes deployment manifests are generated in `config/manager/manager.yaml`. + +Deploy the nginx-operator: + +```sh +make deploy IMG=$IMG +``` + +Verify that the nginx-operator is up and running: + +```sh +$ kubectl get deployment -n nginx-operator-system +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +nginx-operator-controller-manager 1/1 1 1 1 77s +``` + +### 2. Run outside the cluster + +This method is preferred during the development cycle to speed up deployment and testing. + +Run the operator locally with the default Kubernetes config file present at +`$HOME/.kube/config`: + +```sh +$ make run +INFO[0000] Go Version: go1.10.3 +INFO[0000] Go OS/Arch: linux/amd64 +INFO[0000] operator-sdk Version: v0.1.1+git +``` + +Run the operator locally with a provided Kubernetes config file: + +```sh +$ operator-sdk run local --kubeconfig= +INFO[0000] Go Version: go1.10.3 +INFO[0000] Go OS/Arch: linux/amd64 +INFO[0000] operator-sdk Version: v0.2.0+git +``` + +### 3. Deploy your Operator with the Operator Lifecycle Manager (OLM) + +OLM will manage creation of most if not all resources required to run your operator, +using a bit of setup from other `operator-sdk` commands. Check out the OLM integration +[user guide][quickstart-bundle] for more information. + +## Deploy the Nginx custom resource + +Apply the nginx CR that we modified earlier: + +```sh +$ kubectl apply -f config/samples/example_v1alpha1_nginx.yaml +``` + +Ensure that the nginx-operator creates the deployment for the CR: + +```sh +$ kubectl get deployment +NAME READY UP-TO-DATE AVAILABLE AGE +nginx-sample 2/2 2 2 2m13s +``` + +Check the pods to confirm 2 replicas were created: + +```sh +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +nginx-sample-c786bfdcf-4g6md 1/1 Running 0 81s +nginx-sample-c786bfdcf-6bhmx 1/1 Running 0 81s + +Check that the service port is set to `8080`: + +```sh +$ kubectl get service +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +nginx-sample ClusterIP 10.96.26.3 8080/TCP 1m +``` + +### Update the replicaCount and remove the port + +Change the `spec.replicaCount` field from 2 to 3, remove the `spec.service` +field: + +```sh +$ cat config/samples/example_v1alpha1_nginx.yaml +apiVersion: example.com/v1alpha1 +kind: Nginx +metadata: + name: nginx-sample +spec: + replicaCount: 3 +``` + +And apply the change: +```sh +$ kubectl apply -f config/samples/example_v1alpha1_nginx.yaml +``` + +Confirm that the operator changes the deployment size: + +```sh +$ kubectl get deployment +NAME DESIRED CURRENT UP-TO-DATE AGE +nginx-sample 3/3 3 3 7m29s +``` + +Check that the service port is set to the default (`80`): + +```sh +$ kubectl get service +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +nginx-sample ClusterIP 10.96.152.76 80/TCP 7m54s +``` + +### Troubleshooting + +Use the following command to check the operator logs. + +```sh +$ kubectl logs deployment.apps/nginx-operator-controller-manager -n nginx-operator-system -c manager +``` + +Use the following command to check the CR status and events. + +```sh +$ kubectl describe nginxes.example.com +``` + +### Cleanup + +Clean up the resources: + +```sh +$ kubectl delete -f config/samples/example_v1alpha1_nginx.yaml +$ make undeploy +``` +**NOTE** Additional CR/CRD's can be added to the project by running, for example, the command :`operator-sdk create api --group=example --version=v1alpha1 --kind=AppService` + + +[operator-scope]: /docs/building-operators/golang/operator-scope +[layout-doc]: /docs/building-operators/helm/reference/project_layout/ +[helm-charts]:https://helm.sh/docs/topics/charts/ +[helm-values]:https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing +[helm-official]:https://helm.sh/docs/ \ No newline at end of file