Skip to content

Commit

Permalink
doc: migration guide for Ansible and quickstart fixes (#3571)
Browse files Browse the repository at this point in the history 
* doc: ansible add migration guide and update quick

* removing the molecule statments that we are not so sure about

* appling the change made in the templates today

* typo fix
  • Loading branch information
@camilamacedo86
camilamacedo86 authored Aug 5, 2020
1 parent 260e547 commit f04ad07
Show file tree
Hide file tree
Showing 5 changed files with 290 additions and 55 deletions.
2 changes: 1 addition & 1 deletion website/content/en/docs/building-operators/ansible/development-tips.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Development Tips
weight: 12
weight: 5
---

This document provides some useful information and tips for a developer
Expand Down
237 changes: 237 additions & 0 deletions website/content/en/docs/building-operators/ansible/migration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,237 @@
---
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 `molecule/` 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 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

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/<kind>`. We can copy over the content of our old `roles/<kind>` 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/<group>_<version>_<kind>_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
```

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

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
101 changes: 48 additions & 53 deletions website/content/en/docs/building-operators/ansible/quickstart.md
View file
Original file line number Diff line number Diff line change
@@ -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=<some-registry>/<project-name>:tag
make docker-build docker-push IMG=<some-registry>/<project-name>:<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=<some-registry>/<project-name>:tag
make install
make deploy IMG=<some-registry>/<project-name>:<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/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/
[operator_install]: /docs/installation/install-operator-sdk
[layout-doc]:../reference/scaffolding
[tutorial]: /docs/building-operators/ansible/tutorial/
[ansible-link]: https://www.ansible.com/
Loading

0 comments on commit f04ad07

Please sign in to comment.