Skip to content

Commit

Permalink
docs: update helm docs for the new layout (operator-framework#3326)
Browse files Browse the repository at this point in the history 
**Description of the change:**

Provide the same documentation and steps using the helm plugin. See the PR operator-framework#3421 which adds the plugin. 

- Update all related info in the Helm documentation  
- Create a new sub-directory called Legacy to keep the previous docs

**Motivation**

SDK is in a process to be integrated with KB which means that its project layouts will be aligned. More info : [Integrating Kubebuilder and Operator SDK](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/integrating-kubebuilder-and-osdk.md) and [Extensible CLI and Scaffolding Plugins](https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/extensible-cli-and-scaffolding-plugins-phase-1.md).
  • Loading branch information
@camilamacedo86
camilamacedo86 authored Jul 18, 2020
1 parent 25b8054 commit a5daa91
Show file tree
Hide file tree
Showing 7 changed files with 123 additions and 96 deletions.
6 changes: 3 additions & 3 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
### Additions

- Add "panic" level for --zap-stacktrace-level (allows "debug", "info", "error", "panic"). ([#3040](https://github.com/operator-framework/operator-sdk/pull/3040))
- The `operator-sdk` binary has a new CLI workflow and project layout for scaffolding Go operators that is aligned with Kubebuilder's CLI and project layout. See the new [Quickstart Guide](https://master.sdk.operatorframework.io/docs/golang/quickstart) and the new [CLI reference](https://master.sdk.operatorframework.io/docs/new-cli) for more details. ([#3190](https://github.com/operator-framework/operator-sdk/pull/3190))
- The `operator-sdk` binary has a new CLI workflow and project layout for scaffolding Go operators that is aligned with Kubebuilder's CLI and project layout. See the new [Quickstart Guide](https://master.sdk.operatorframework.io/docs/building-operators/golang/quickstart/) and the new [CLI reference](https://master.sdk.operatorframework.io/docs/cli) for more details. ([#3190](https://github.com/operator-framework/operator-sdk/pull/3190))
- `bundle validate` can now use a containerd image ("none") tool to unpack images, removing the need for an external image tool like docker/podman. ([#3222](https://github.com/operator-framework/operator-sdk/pull/3222))
- The SDK `scorecard` command adds a new test image, scorecard-test-kuttl, that allows end users to write and execute kuttl based tests. ([#3278](https://github.com/operator-framework/operator-sdk/pull/3278))
- Add "--olm-namespace" flag to olm subcommands (install, uninstall) to allow users to specify the namespace where olm is to be installed or uninstalled. ([#3300](https://github.com/operator-framework/operator-sdk/pull/3300))
Expand All @@ -29,11 +29,11 @@

### Removals

- The `operator-sdk new` command no longer supports scaffolding new Go projects with the `--type=Go` flag. To scaffold new projects, users are expected to use `operator-sdk init` as part of the [new CLI](https://master.sdk.operatorframework.io/docs/new-cli) for Go operators. ([#3190](https://github.com/operator-framework/operator-sdk/pull/3190))
- The `operator-sdk new` command no longer supports scaffolding new Go projects with the `--type=Go` flag. To scaffold new projects, users are expected to use `operator-sdk init` as part of the [new CLI](https://master.sdk.operatorframework.io/docs/cli) for Go operators. ([#3190](https://github.com/operator-framework/operator-sdk/pull/3190))

### Deprecations

- With the introduction of the new [Kubebuilder aligned CLI](https://master.sdk.operatorframework.io/docs/new-cli) and project layout for Go operators, the [old CLI](https://sdk.operatorframework.io/docs/cli) will still continue to work for Go projects scaffolded in the old layout with `operator-sdk new`. However the old CLI is now deprecated and will be removed in a future release. ([#3190](https://github.com/operator-framework/operator-sdk/pull/3190))
- With the introduction of the new [Kubebuilder aligned CLI](https://master.sdk.operatorframework.io/docs/cli) and project layout for Go operators, the [old CLI](https://sdk.operatorframework.io/docs/cli) will still continue to work for Go projects scaffolded in the old layout with `operator-sdk new`. However the old CLI is now deprecated and will be removed in a future release. ([#3190](https://github.com/operator-framework/operator-sdk/pull/3190))
- The migrate sub-command is deprecated. ([#3319](https://github.com/operator-framework/operator-sdk/pull/3319))
- Deprecate 'operator-sdk add crd'. Use 'operator-sdk add api' instead. ([#3180](https://github.com/operator-framework/operator-sdk/pull/3180))
- `bundle create` is deprecated in favor of a combination of `generate bundle` and `docker build -f bundle.Dockerfile ...`. ([#3323](https://github.com/operator-framework/operator-sdk/pull/3323))
Expand Down
12 changes: 8 additions & 4 deletions website/content/en/docs/building-operators/helm/migration.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
---
title: Helm migration for the new Layout
linkTitle: Migration
weight: 3
---

This guide walks through an example of migrating a simple nginx-operator which was built by following the [legacy quick-start][quickstart] to the new layout.
This guide walks through an example of migrating a simple nginx-operator which was built by following the [legacy quick-start][quickstart-legacy] to the new layout.

## Overview

Expand Down Expand Up @@ -38,7 +43,7 @@ $ operator-sdk init --plugins=helm.operator-sdk.io/v1 --domain=com --group=examp
```

**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-new].
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

Expand All @@ -51,9 +56,8 @@ more than one chart or API's you can add them via `operator-sdk create api` comm

Now, follow the steps in the section [Build and run the operator][build-run-quick] to verify your project is running.

<!-- todo: update the following link to /docs/helm/legacy/quickstart when the PR #3326 get merged -->
[quickstart-legacy]: https://v0-19-x.sdk.operatorframework.io/docs/helm/quickstart/
[quickstart]: /docs/building-operators/helm/quickstart
[quickstart-new]: /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
[kustomize]: https://github.com/kubernetes-sigs/kustomize
148 changes: 77 additions & 71 deletions website/content/en/docs/building-operators/helm/quickstart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,19 @@ This guide walks through an example of building a simple nginx-operator powered
Use the CLI to create a new Helm-based nginx-operator project:

```sh
operator-sdk new nginx-operator --api-version=example.com/v1alpha1 --kind=Nginx --type=helm
cd nginx-operator
$ mkdir nginx-operator
$ cd nginx-operator
$ operator-sdk init --plugins=helm.operator-sdk.io/v1 --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 new` also generates the RBAC rules
in `deploy/role.yaml` based on the resources that would be deployed by the
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 `deploy/role.yaml` meet the operator's permission requirements.
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.
Expand All @@ -31,17 +32,26 @@ To learn more about the project directory structure, see the

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, `--api-version` and `--kind` become optional. If left unset, the SDK will default `--api-version` to `charts.helm.k8s.io/v1alpha1` and will deduce `--kind` from the specified chart.
If `--helm-chart` is specified, the `--group`, `--version`, and `--kind` flags become optional. If left unset, the default will be:

If `--helm-chart` is a local chart archive or directory, it will be validated and unpacked or copied into the project.
| 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:

- `<repoName>/<chartName>`: Fetch the helm chart named `chartName` from the helm
chart repository named `repoName`, as specified in the
$HELM_HOME/repositories/repositories.yaml file.
`$HELM_HOME/repositories/repositories.yaml` file.
Use [`helm repo add`](https://helm.sh/docs/helm/helm_repo_add) to configure this file.

- `<url>`: Fetch the helm chart archive at the specified URL.

Expand All @@ -52,7 +62,7 @@ If a custom repository URL is specified by `--helm-chart-repo`, the only support

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 new --help`.
**Note:** For more details and examples run `operator-sdk init --plugins=helm.operator-sdk.io/v1 --help`.

### Operator scope

Expand All @@ -75,11 +85,12 @@ By default, the nginx-operator watches `Nginx` resource events as shown
in `watches.yaml` and executes Helm releases using the specified chart:

```yaml
---
- version: v1alpha1
group: example.com
# 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
Expand All @@ -88,7 +99,7 @@ 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
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
Expand All @@ -108,19 +119,19 @@ 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 `deploy/crds/example.com_v1alpha1_nginx_cr.yaml` to look like the following:
Update `config/samples/example_v1alpha1_nginx.yaml` to look like the following:

```yaml
apiVersion: example.com/v1alpha1
kind: Nginx
metadata:
name: example-nginx
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 `deploy/crds/example.com_v1alpha1_nginx_cr.yaml`
like to use `8080`, so we'll again update `config/samples/example_v1alpha1_nginx.yaml`
by adding the service port override:

```yaml
Expand All @@ -146,7 +157,7 @@ resource definition the operator will be watching.
Deploy the CRD:

```sh
kubectl create -f deploy/crds/example.com_nginxes_crd.yaml
make install
```

Once this is done, there are two ways to run the operator:
Expand All @@ -161,40 +172,24 @@ 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
operator-sdk build quay.io/example/nginx-operator:v0.0.1
docker push quay.io/example/nginx-operator:v0.0.1
```

Kubernetes deployment manifests are generated in `deploy/operator.yaml`. The
deployment image in this file needs to be modified from the placeholder
`REPLACE_IMAGE` to the previous built image. To do this run:

```sh
sed -i 's|REPLACE_IMAGE|quay.io/example/nginx-operator:v0.0.1|g' deploy/operator.yaml
export IMG=quay.io/example/nginx-operator:v0.0.1
make docker-build docker-push IMG=$IMG
```

**Note**
If you are performing these steps on OSX, use the following `sed` command instead:

```sh
sed -i "" 's|REPLACE_IMAGE|quay.io/example/nginx-operator:v0.0.1|g' deploy/operator.yaml
```
**Note:** Kubernetes deployment manifests are generated in `config/manager/manager.yaml`.

Deploy the nginx-operator:

```sh
kubectl create -f deploy/service_account.yaml
kubectl create -f deploy/role.yaml
kubectl create -f deploy/role_binding.yaml
kubectl create -f deploy/operator.yaml
make deploy IMG=$IMG
```

Verify that the nginx-operator is up and running:

```sh
$ kubectl get deployment
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
nginx-operator 1 1 1 1 1m
$ 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
Expand All @@ -205,7 +200,7 @@ Run the operator locally with the default Kubernetes config file present at
`$HOME/.kube/config`:

```sh
$ operator-sdk run local
$ 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
Expand All @@ -231,87 +226,98 @@ using a bit of setup from other `operator-sdk` commands. Check out the OLM integ
Apply the nginx CR that we modified earlier:

```sh
kubectl apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml
$ 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 DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
example-nginx-b9phnoz9spckcrua7ihrbkrt1 2 2 2 2 1m
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
example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-fjcr9 1/1 Running 0 1m
example-nginx-b9phnoz9spckcrua7ihrbkrt1-f8f9c875d-ljbzl 1/1 Running 0 1m
```
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
example-nginx-b9phnoz9spckcrua7ihrbkrt1 ClusterIP 10.96.26.3 <none> 8080/TCP 1m
nginx-sample ClusterIP 10.96.26.3 <none> 8080/TCP 1m
```

### Update the replicaCount and remove the port

Change the `spec.replicaCount` field from 2 to 3, remove the `spec.service`
field, and apply the change:
field:

```sh
$ cat deploy/crds/example.com_v1alpha1_nginx_cr.yaml
apiVersion: "example.com/v1alpha1"
kind: "Nginx"
$ cat config/samples/example_v1alpha1_nginx.yaml
apiVersion: example.com/v1alpha1
kind: Nginx
metadata:
name: "example-nginx"
name: nginx-sample
spec:
replicaCount: 3
```

$ kubectl apply -f deploy/crds/example.com_v1alpha1_nginx_cr.yaml
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 AVAILABLE AGE
example-nginx-b9phnoz9spckcrua7ihrbkrt1 3 3 3 3 1m
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
example-nginx-b9phnoz9spckcrua7ihrbkrt1 ClusterIP 10.96.26.3 <none> 80/TCP 1m
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx-sample ClusterIP 10.96.152.76 <none> 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 deploy/crds/example.com_v1alpha1_nginx_cr.yaml
kubectl delete -f deploy/operator.yaml
kubectl delete -f deploy/role_binding.yaml
kubectl delete -f deploy/role.yaml
kubectl delete -f deploy/service_account.yaml
kubectl delete -f deploy/crds/example.com_nginxes_crd.yaml
$ 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 add api --api-version=cache.example.com/v1alpha1 --kind=AppService`
For more information, refer [cli][addcli] doc.
**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]:https://v0-19-x.sdk.operatorframework.io/docs/legacy-common/operator-scope/
<!--
todo(camilamacedo86): https://github.com/operator-framework/operator-sdk/issues/3447
-->
[operator-scope]: /docs/building-operators/golang/operator-scope
[layout-doc]: /docs/building-operators/helm/reference/scaffolding
[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/
[addcli]: /docs/cli/ansible-helm/operator-sdk_add_api
<!-- TODO: update this link to the non-legacy doc once the helm plugin is publicly available -->
[quickstart-bundle]:https://v0-19-x.sdk.operatorframework.io/docs/olm-integration/legacy/quickstart-bundle/
Loading

0 comments on commit a5daa91

Please sign in to comment.