From ef11ac8902529fac889b8a21a535dfebcebf3913 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Mon, 27 Jul 2020 20:26:26 +0100 Subject: [PATCH] doc: migration guide for Ansbile --- .../ansible/development-tips.md | 2 +- .../building-operators/ansible/migration.md | 258 ++++++++++++++++++ .../building-operators/ansible/quickstart.md | 100 ++++--- .../{scaffolding.md => project_layout.md} | 0 .../building-operators/ansible/tutorial.md | 2 +- .../upgrading-sdk-version/v1.0.0-alpha.1.md | 2 +- 6 files changed, 308 insertions(+), 56 deletions(-) create mode 100644 website/content/en/docs/building-operators/ansible/migration.md rename website/content/en/docs/building-operators/ansible/reference/{scaffolding.md => project_layout.md} (100%) 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 fbad93e7d98..0afb8616631 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: 6 --- 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..a91b7b41d88 --- /dev/null +++ b/website/content/en/docs/building-operators/ansible/migration.md @@ -0,0 +1,258 @@ +--- +title: Migrating Legacy Projects +linkTitle: Migrating Legacy Projects +weight: 7 +--- + +This guide walks through an example of migrating a simple memcached-operator which was built by following the [legacy quick-start][quickstart-legacy] to the new 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` was replaced for `config/manager/manager.yaml` +- RBAC manifests in `deploy` are in `config/rbac/` + +The `build/Dockerfile` directory was replaced by the `Dockerfile` in the root directory + +### What is new + +Projects are now scaffold using: + +- [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 files properly and then, +just replace with your customizations and implementations. Following 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 re-create each of our APIs. +Using our API example from earlier (`cache.example.com`), we'll use `cache` for the +`--group` flag. + +For each API in the existing project which is using an Ansible role, run: +```sh +$ operator-sdk create api \ + --group=cache \ + --api-version= \ + --kind= +``` + +**Note** Ensure that you use the same values for the flags to recreate the same API's. If you have more than one API you can add them via `operator-sdk create api` command. For further information check the [Ansible Quickstart][quickstart]. + +After run the above command we will check that the `roles/` directory was created for the Kind but it is empty. So, we will copy the content of the `roles/` directory of our old project 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` [Maker][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:-""} + operator_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 + +In case your project has customizations in the `deploy/operator.yaml` then, it needs to be port to +`config/manager/manager.yaml`. However, note that the following env vars 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` 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 + +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. + +## Enabling Ansible Logs + +If you would like to enable the Ansible Logs to check yur project update the `config/manager/manager.yaml` with the environment variable `ANSIBLE_DEBUG_LOGS` as `True`: + +```yaml +... + containers: + - name: manager + args: + - "--enable-leader-election" + - "--leader-election-id=memcached-operator" + image: controller:latest + env: + - name: ANSIBLE_DEBUG_LOGS + value: "True" + terminationGracePeriodSeconds: 10 +``` + +## 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#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 +[operator-scope]: /docs/building-operators/golang/operator-scope +[molecule]: https://molecule.readthedocs.io/en/latest/# +[testing-guide]: /docs/building-operators/ansible/testing-guide \ No newline at end of file diff --git a/website/content/en/docs/building-operators/ansible/quickstart.md b/website/content/en/docs/building-operators/ansible/quickstart.md index 1923317cc83..2611ee2c5de 100644 --- a/website/content/en/docs/building-operators/ansible/quickstart.md +++ b/website/content/en/docs/building-operators/ansible/quickstart.md @@ -1,96 +1,90 @@ --- -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 Helm 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 requisites][ansible-operator-install] +- Access to a Kubernetes v1.16.0+ cluster. -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][project_layout]: ```sh -$ make install +mkdir -p $HOME/projects/memcached-operator +cd $HOME/projects/memcached-operator +operator-sdk init --plugins=ansible ``` -## 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=/:tag ``` -**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=/:tag ``` -## 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/demo_v1_nginx.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 the release: ```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 +[project_layout]: /docs/building-operators/ansible/reference/project_layout/ +[tutorial]: /docs/building-operators/ansible/tutorial/ \ No newline at end of file diff --git a/website/content/en/docs/building-operators/ansible/reference/scaffolding.md b/website/content/en/docs/building-operators/ansible/reference/project_layout.md similarity index 100% rename from website/content/en/docs/building-operators/ansible/reference/scaffolding.md rename to website/content/en/docs/building-operators/ansible/reference/project_layout.md diff --git a/website/content/en/docs/building-operators/ansible/tutorial.md b/website/content/en/docs/building-operators/ansible/tutorial.md index b4e38ae249d..27f62867a6e 100644 --- a/website/content/en/docs/building-operators/ansible/tutorial.md +++ b/website/content/en/docs/building-operators/ansible/tutorial.md @@ -369,7 +369,7 @@ For more information, refer [cli][addcli] doc. [ansible-runner-tool]: https://ansible-runner.readthedocs.io/en/latest/install.html [ansible-watches]: /docs/building-operators/ansible/reference/watches [operator-scope]:https://v0-19-x.sdk.operatorframework.io/docs/legacy-common/operator-scope/ -[layout-doc]:../reference/scaffolding +[layout-doc]: /docs/building-operators/ansible/reference/project_layout [homebrew-tool]:https://brew.sh/ [install-guide]: /docs/installation/install-operator-sdk [git-tool]:https://git-scm.com/downloads diff --git a/website/content/en/docs/upgrading-sdk-version/v1.0.0-alpha.1.md b/website/content/en/docs/upgrading-sdk-version/v1.0.0-alpha.1.md index 20b83142bc1..c3fbdaba0da 100644 --- a/website/content/en/docs/upgrading-sdk-version/v1.0.0-alpha.1.md +++ b/website/content/en/docs/upgrading-sdk-version/v1.0.0-alpha.1.md @@ -10,7 +10,7 @@ Kubebuilder-style layout. - [Go](https://master.sdk.operatorframework.io/docs/building-operators/golang/project_migration_guide/) -- [Ansible](https://github.com/operator-framework/operator-sdk/pull/3571) (PR in progress) +- [Ansible](https://master.sdk.operatorframework.io/docs/building-operators/ansible/project_migration_guide/) - [Helm](https://master.sdk.operatorframework.io/docs/building-operators/helm/migration/) The following subcommands were removed: