From 2b00cb45969e12d75ae5d552c9c044f6ee028d22 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Thu, 30 Jul 2020 18:14:55 +0100 Subject: [PATCH 1/4] doc: ansible add migration guide and update quick --- .../ansible/development-tips.md | 2 +- .../building-operators/ansible/migration.md | 242 ++++++++++++++++++ .../building-operators/ansible/quickstart.md | 101 ++++---- .../ansible/testing-guide.md | 2 +- .../building-operators/ansible/tutorial.md | 3 + 5 files changed, 295 insertions(+), 55 deletions(-) create mode 100644 website/content/en/docs/building-operators/ansible/migration.md diff --git a/website/content/en/docs/building-operators/ansible/development-tips.md b/website/content/en/docs/building-operators/ansible/development-tips.md index 49ee5a9d2d5..9370f3f76ad 100644 --- a/website/content/en/docs/building-operators/ansible/development-tips.md +++ b/website/content/en/docs/building-operators/ansible/development-tips.md @@ -1,6 +1,6 @@ --- title: Development Tips -weight: 12 +weight: 5 --- This document provides some useful information and tips for a developer diff --git a/website/content/en/docs/building-operators/ansible/migration.md b/website/content/en/docs/building-operators/ansible/migration.md new file mode 100644 index 00000000000..3a3faa7f708 --- /dev/null +++ b/website/content/en/docs/building-operators/ansible/migration.md @@ -0,0 +1,242 @@ +--- +title: Migrating Legacy Projects +linkTitle: Migrating Projects to 1.0.0+ +weight: 6 +description: Instructions for migrating a Ansible-based project built prior to 1.0.0 to use the new Kubebuilder-style layout. +--- + +## Overview + +The motivations for the new layout are related to bringing more flexibility to users and +part of the process to [Integrating Kubebuilder and Operator SDK][integration-doc]. + +### What was changed + +- The `deploy` directory was replaced with the `config` directory including a new layout of Kubernetes manifests files: + * CRD manifests in `deploy/crds/` are now in `config/crd/bases` + * CR manifests in `deploy/crds/` are now in `config/samples` + * Controller manifest `deploy/operator.yaml` is now in `config/manager/manager.yaml` + * RBAC manifests in `deploy` are now in `config/rbac/` + +- `build/Dockerfile` is moved to `Dockerfile` in the project root directory +- The `molecue/` directory is now more aligned to Ansible and the new Layout + +### What is new + +Scaffolded projects now use: + +- [kustomize][kustomize] to manage Kubernetes resources needed to deploy your operator +- A `Makefile` with helpful targets for build, test, and deployment, and to give you flexibility to tailor things to your project's needs +- Updated metrics configuration using [kube-auth-proxy][kube-auth-proxy], a `--metrics-addr` flag, and [kustomize][kustomize]-based deployment of a Kubernetes `Service` and prometheus operator `ServiceMonitor` + +## How to migrate + +The easy migration path is to create a new project from the scratch and let the tool scaffold the new layout. Then, add your customizations and implementations. See below for an example. + +### Creating a new project + +In Kubebuilder-style projects, CRD groups are defined using two different flags +(`--group` and `--domain`). + +When we initialize a new project, we need to specify the domain that _all_ APIs in +our project will share, so before creating the new project, we need to determine which +domain we're using for the APIs in our existing project. + +To determine the domain, look at the `spec.group` field in your CRDs in the +`deploy/crds` directory. + +The domain is everything after the first DNS segment. Using `cache.example.com` as an +example, the `--domain` would be `example.com`. + +So let's create a new project with the same domain (`example.com`): + +```sh +mkdir memcached-operator +cd memcached-operator +operator-sdk init --plugins=ansible --domain=example.com +``` + +Now that we have our new project initialized, we need to recreate 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 \ + --version=v1 \ + --kind=Memcached +``` + +Running the above command creates an empty `roles/`. We can copy over the content of our old `roles/` to the new one. + +### 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` In our example +the `config/samples/cache_v1alpha1_memcached.yaml` will look like: + +```yaml +apiVersion: cache.example.com/v1alpha1 +kind: Memcached +metadata: + name: memcached-sample +spec: + # Add fields here + size: 3 +``` + +### Migrating `watches.yaml + +Update the `watches.yaml` file with your `roles/playbooks` and 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, we will replace `# FIXME: Specify the role or playbook for this resource.` with our previous role and it will look like: + +```yaml +--- +# Use the 'create api' subcommand to add watches to this file. +- version: v1alpha1 + group: cache.example.com + kind: Memcached + role: memcached +# +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. + +### Migrating your Molecule tests + +If you are using [Molecule][molecule] in your project will be required to port the tests for the new layout. + +See that default structure changed from: + +```sh +├── cluster +│   ├── converge.yml +│   ├── create.yml +│   ├── destroy.yml +│   ├── molecule.yml +│   ├── prepare.yml +│   └── verify.yml +├── default +│   ├── converge.yml +│   ├── molecule.yml +│   ├── prepare.yml +│   └── verify.yml +├── templates +│   └── operator.yaml.j2 +└── test-local + ├── converge.yml + ├── molecule.yml + ├── prepare.yml + └── verify.yml + +``` + +To: + +``` +├── default +│   ├── converge.yml +│   ├── create.yml +│   ├── destroy.yml +│   ├── kustomize.yml +│   ├── molecule.yml +│   ├── prepare.yml +│   ├── tasks +│   │   └── foo_test.yml +│   └── verify.yml +└── kind + ├── converge.yml + ├── create.yml + ├── destroy.yml + └── molecule.yml +``` + +And now: + +- Use the var `${MOLECULE_PROJECT_DIRECTORY}` instead of `${MOLECULE_EPHEMERAL_DIRECTORY}` +- Use the var `${KUBECONFIG:-"~/.kube/config"}` instead of `${MOLECULE_EPHEMERAL_DIRECTORY}/kubeconfig` to get the kubeconfig + +Also, ensure that the `provisioner.host_vars.localhost` has the following `host_vars`: + +``` +.... + host_vars: + localhost: + ansible_python_interpreter: '{{ ansible_playbook_python }}' + config_dir: ${MOLECULE_PROJECT_DIRECTORY}/config + samples_dir: ${MOLECULE_PROJECT_DIRECTORY}/config/samples + operator_image: ${OPERATOR_IMAGE:-""} + pull_policy: ${OPERATOR_PULL_POLICY:-"Always"} + kustomize: ${KUSTOMIZE_PATH:-kustomize} +... +``` + +For more information read the [Testing with Molecule][testing-guide]. + +### 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 anisible-operator to automatically create and manage services and `servicemonitors` for metrics collection. If your operator's don't require these rules, they can safely be left out of the new `config/rbac/role.yaml` file: + +```yaml + - 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. + +- `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` has been removed. It was used to enable a particular pod to hold the leader election lock when the Ansible operator used the leader for life mechanism. Ansible operator now uses controller-runtime's leader with lease mechanism. + +## Exporting metrics + +If you are using metrics and would like to keep them exported you will need to configure +it in the `config/default/kustomization.yaml`. Please see the [metrics][metrics] doc to know how you can perform this setup. + +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 + +Finally, follow the steps in the section [Build and run the Operator][build-and-run-the-operator] to verify your project is running. + +Note that, you also can troubleshooting by checking the container logs. +E.g `$ kubectl logs deployment.apps/memcached-operator-controller-manager -n memcached-operator-system -c manager` + +[quickstart-legacy]: https://v0-19-x.sdk.operatorframework.io/docs/ansible/quickstart/ +[quickstart]: /docs/building-operators/ansible/quickstart +[integration-doc]: https://github.com/kubernetes-sigs/kubebuilder/blob/master/designs/integrating-kubebuilder-and-osdk.md +[build-and-run-the-operator]: /docs/building-operators/ansible/tutorial/#deploy-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 +[operator-scope]: /docs/building-operators/golang/operator-scope +[molecule]: https://molecule.readthedocs.io/en/latest/# +[testing-guide]: /docs/building-operators/ansible/testing-guide diff --git a/website/content/en/docs/building-operators/ansible/quickstart.md b/website/content/en/docs/building-operators/ansible/quickstart.md index 1923317cc83..b7cad11e6fd 100644 --- a/website/content/en/docs/building-operators/ansible/quickstart.md +++ b/website/content/en/docs/building-operators/ansible/quickstart.md @@ -1,96 +1,91 @@ --- -title: Ansible Operator QuickStart -linkTitle: QuickStart +title: Quickstart for Ansible-based Operators +linkTitle: Quickstart weight: 2 +description: A simple set of instructions that demonstrates the basics of setting up and running a Ansible-based operator. --- -## Prerequisites - -- [docker][docker_tool] version 17.03+. -- [kubectl][kubectl_tool] version v1.11.3+. -- [Ansible Operator SDK Installation][ansible-operator-install] v1.0.0+ -- Access to a Kubernetes v1.11.3+ cluster. -## Creating a Project +This guide walks through an example of building a simple memcached-operator powered by [Ansible][ansible-link] using tools and libraries provided by the Operator SDK. -Create a directory, and then run the init command inside of it to generate a new project. - -```sh -$ mkdir $GOPATH/src/memcached-operator -$ cd $GOPATH/src/memcached-operator -$ operator-sdk init --plugins=ansible -``` +## Prerequisites -## Creating an API +- [Install `operator-sdk`][operator_install] and the [Ansible prequisites][ansible-operator-install] +- Access to a Kubernetes v1.16.0+ cluster. +- User authorized with `cluster-admin` permissions. -Let's create a new API with a default role for it: +## Quickstart Steps -```sh -$ operator-sdk create api --group cache --version v1 --kind Memcached --generate-role -``` +### Create a project -## Applying the CRDs into the cluster: - -To apply the `Memcached` Kind(CRD): +Create and change into a directory for your project. Then call `operator-sdk init` +with the Ansible plugin to initialize the [base project layout][layout-doc]: ```sh -$ make install +mkdir memcached-operator +cd memcached-operator +operator-sdk init --plugins=ansible --domain=example.com ``` -## Running it locally +### Create an API -To run the project out of the cluster: +Let's create a new API with a role for it: ```sh -$ make run +operator-sdk create api --group cache --version v1 --kind Memcached --generate-role ``` -## Building and Pushing the Project Image +### Build and push the operator image -To build and push your image to your repository : +Use the built-in Makefile targets to build and push your operator. Make +sure to define `IMG` when you call `make`: ```sh -$ make docker-build docker-push IMG=/:tag +make docker-build docker-push IMG=/: ``` -**Note** To allow the cluster pull the image the repository needs to be set as public. +**NOTE**: To allow the cluster pull the image the repository needs to be + set as public or you must configure an image pull secret. + -## Running it on Cluster +### Run the operator -Deploy the project to the cluster: +Install the CRD and deploy the project to the cluster. Set `IMG` with +`make deploy` to use the image you just pushed: ```sh -$ make deploy IMG=/:tag +make install +make deploy IMG=/: ``` -## Applying the CR's into the cluster: - -To create instances (CR's) of the `Memcached` Kind (CRD) in the same namespaced of the operator +### Create a sample custom resource +Create a sample CR: ```sh -$ kubectl apply -f config/samples/cache_v1alpha1_memcached.yaml -n memcached-operator-system +kubectl apply -f config/samples/cache_v1_memcached.yaml ``` -## Uninstall CRDs +Watch for the CR be reconciled by the operator: +```sh +kubectl logs deployment.apps/memcached-operator-controller-manager -n memcached-operator-system -c manager +``` -To delete your CRDs from the cluster: +### Clean up +Delete the CR to uninstall memcached: ```sh -$ make uninstall +kubectl delete -f config/samples/cache_v1_memcached.yaml ``` -## Undeploy Project - +Use `make undeploy` to uninstall the operator and its CRDs: ```sh -$ make undeploy +make undeploy ``` -## Next Step +## Next Steps -Now, follow up the [Tutorial][tutorial] to better understand how it works by developing a demo project. +Read the [tutorial][tutorial] for an in-depth walkthough of building a Ansible operator. -[docker_tool]:https://docs.docker.com/install/ -[kubectl_tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ -[ansible-operator-install]: /docs/building-operators/ansible/installation -[helm-repo-add]: https://helm.sh/docs/helm/helm_repo_add -[helm-chart-memcached]: https://github.com/helm/charts/tree/master/stable/memcached -[tutorial]: /docs/building-operators/ansible/tutorial/ \ No newline at end of file +[operator_install]: /docs/installation/install-operator-sdk +[layout-doc]:../reference/scaffolding +[tutorial]: /docs/building-operators/ansible/tutorial/ +[ansible-link]: https://www.ansible.com/ diff --git a/website/content/en/docs/building-operators/ansible/testing-guide.md b/website/content/en/docs/building-operators/ansible/testing-guide.md index ddff656f0a6..eeccc87d2fb 100644 --- a/website/content/en/docs/building-operators/ansible/testing-guide.md +++ b/website/content/en/docs/building-operators/ansible/testing-guide.md @@ -1,7 +1,7 @@ --- title: Ansible Based Operator Testing with Molecule linkTitle: Testing with Molecule -weight: 5 +weight: 4 --- ## Getting started diff --git a/website/content/en/docs/building-operators/ansible/tutorial.md b/website/content/en/docs/building-operators/ansible/tutorial.md index f657b2033d0..9fd2715b597 100644 --- a/website/content/en/docs/building-operators/ansible/tutorial.md +++ b/website/content/en/docs/building-operators/ansible/tutorial.md @@ -2,6 +2,7 @@ title: Ansible Operator Tutorial linkTitle: Tutorial weight: 3 +description: An in-depth walkthough that demonstrates how to build and run a Ansible-based operator. --- This guide walks through an example of building a simple memcached-operator powered by Ansible using tools and libraries provided by the Operator SDK. @@ -10,6 +11,7 @@ This guide walks through an example of building a simple memcached-operator powe - [Install `operator-sdk`][operator_install] and the [Ansible prequisites][ansible-operator-install] - Access to a Kubernetes v1.16.0+ cluster. +- User authorized with `cluster-admin` permissions. ## Creating an Operator @@ -230,3 +232,4 @@ OLM will manage creation of most if not all resources required to run your opera [docker-tool]:https://docs.docker.com/install/ [kubectl-tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/ [quickstart-bundle]: /docs/olm-integration/quickstart-bundle/ +[operator_install]: /docs/installation/install-operator-sdk From 0b2544dfadd055137ef0a8cd033de0db94993c27 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Wed, 5 Aug 2020 22:46:32 +0100 Subject: [PATCH 2/4] removing the molecule statments that we are not so sure about --- .../en/docs/building-operators/ansible/migration.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/website/content/en/docs/building-operators/ansible/migration.md b/website/content/en/docs/building-operators/ansible/migration.md index 3a3faa7f708..8173580b2fe 100644 --- a/website/content/en/docs/building-operators/ansible/migration.md +++ b/website/content/en/docs/building-operators/ansible/migration.md @@ -155,12 +155,7 @@ To: └── molecule.yml ``` -And now: - -- Use the var `${MOLECULE_PROJECT_DIRECTORY}` instead of `${MOLECULE_EPHEMERAL_DIRECTORY}` -- Use the var `${KUBECONFIG:-"~/.kube/config"}` instead of `${MOLECULE_EPHEMERAL_DIRECTORY}/kubeconfig` to get the kubeconfig - -Also, ensure that the `provisioner.host_vars.localhost` has the following `host_vars`: +Ensure that the `provisioner.host_vars.localhost` has the following `host_vars`: ``` .... From 1291ac590582bea9d424d90370fbfcac8b35f24d Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Wed, 5 Aug 2020 22:51:04 +0100 Subject: [PATCH 3/4] appling the change made in the templates today --- website/content/en/docs/building-operators/ansible/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/en/docs/building-operators/ansible/migration.md b/website/content/en/docs/building-operators/ansible/migration.md index 8173580b2fe..91edce892a0 100644 --- a/website/content/en/docs/building-operators/ansible/migration.md +++ b/website/content/en/docs/building-operators/ansible/migration.md @@ -165,7 +165,7 @@ Ensure that the `provisioner.host_vars.localhost` has the following `host_vars`: config_dir: ${MOLECULE_PROJECT_DIRECTORY}/config samples_dir: ${MOLECULE_PROJECT_DIRECTORY}/config/samples operator_image: ${OPERATOR_IMAGE:-""} - pull_policy: ${OPERATOR_PULL_POLICY:-"Always"} + operator_pull_policy: ${OPERATOR_PULL_POLICY:-"Always"} kustomize: ${KUSTOMIZE_PATH:-kustomize} ... ``` From 90aa9925736acc654094ebeb8b8796dcd6650a33 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Wed, 5 Aug 2020 22:55:53 +0100 Subject: [PATCH 4/4] typo fix --- .../content/en/docs/building-operators/ansible/migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/en/docs/building-operators/ansible/migration.md b/website/content/en/docs/building-operators/ansible/migration.md index 91edce892a0..05f48573e14 100644 --- a/website/content/en/docs/building-operators/ansible/migration.md +++ b/website/content/en/docs/building-operators/ansible/migration.md @@ -19,7 +19,7 @@ part of the process to [Integrating Kubebuilder and Operator SDK][integration-do * RBAC manifests in `deploy` are now in `config/rbac/` - `build/Dockerfile` is moved to `Dockerfile` in the project root directory -- The `molecue/` directory is now more aligned to Ansible and the new Layout +- The `molecule/` directory is now more aligned to Ansible and the new Layout ### What is new @@ -31,7 +31,7 @@ Scaffolded projects now use: ## How to migrate -The easy migration path is to create a new project from the scratch and let the tool scaffold the new layout. Then, add your customizations and implementations. See below for an example. +The easy migration path is to a project from the scratch and let the tool scaffold the new layout. Then, add your customizations and implementations. See below for an example. ### Creating a new project