An in-depth walkthough of building and running an Ansible-based operator.
Useful Ansible commands. Make sure python will load all modules installed in your virtualenv.
NOTE: If your project was created with an
operator-sdk
version prior to v1.0.0
please migrate, or consult the legacy docs.Prerequisites
- Go through the installation guide.
- User authorized with
cluster-admin
permissions. - An accessible image registry for various operator images (ex. hub.docker.com,quay.io) and be logged in in your command line environment.
example.com
is used as the registry Docker Hub namespace in these examples.Replace it with another value if using a different registry or namespace.- Authentication and certificates if the registry is private or uses a custom CA.
- Ansible Cheat Sheet Ansible is an open source Continuous Deployment, Configuration Management, & Orchestration. This tool aims to provide large productivity gains to a wide variety of automation challenges and is powerful enough to automate complex multi-tier IT application environments.
- Ansible includes a shell module that can be used to execute commands on remote machines. Issue the command: ansible-playbook myfile.yml -ask-become-pass. A cheat sheet (TechRepublic) 10.
- This guide has been done as a reference guide/cheat sheet for Ansible enthusiasts using Vault to ensure data is encrypted and secured when working on Ansible Projects. Ansible has proven to be the most used and Loved configuration management tool for Developers and SysAdmins of all classes.
- For a quick reference of important Ansible commands, download our Ansible cheat sheet. Automate your container orchestration with Ansible modules for Kubernetes Combine Ansible with Kubernetes for cloud automation.
Overview
We will create a sample project to let you know how it works and this sample will:
- Create a Memcached Deployment if it doesn’t exist
- Ensure that the Deployment size is the same as specified by the Memcached CR spec
- Update the Memcached CR status using the status writer with the names of the CR’s pods
Create a new project
Use the CLI to create a new memcached-operator project:
Among the files generated by this command is a Kubebuilder
PROJECT
file. Subsequent operator-sdk
commands (and help text) run from theproject root read this file and are aware that the project type isAnsible.![Ansible commands cheat sheet printable Ansible commands cheat sheet printable](https://img.17qq.com/images/hrqhuctshrx.jpeg)
Next, we will create a
Memcached
API.Eclipse visual studio. The scaffolded operator has the following structure:
Memcached
Custom Resource Definition, and a sampleMemcached
resource.- A “Manager” that reconciles the state of the cluster to the desired state
- A reconciler, which is an Ansible Role or Playbook.
- A
watches.yaml
file, which connects theMemcached
resource to thememcached
Ansible Role.
See scaffolded files reference and watches reference for more detailed information
Modify the Manager
Now we need to provide the reconcile logic, in the form of an AnsibleRole, which will run every time a
Memcached
resource is created,updated, or deleted.Update
roles/memcached/tasks/main.yml
:This memcached role will:
- Ensure a memcached Deployment exists
- Set the Deployment size
Note that the tasks in this Ansible role file are what actually defines the behavior of the spec and status of the memcached custom resource.As Kubernetes allows entry of arbitrary fields when creating resources, we don’t need to actually create specific fields in the CRD.While we won’t be doing this in this tutorial, it is recommended to also define these fields in the CRD, so that Kubernetes userscan see the fields that will be used when using the custom resource.It is also good practice to set default values for variables used in AnsibleRoles, so edit
roles/memcached/defaults/main.yml
:Finally, update the
Memcached
sample, config/samples/cache_v1alpha1_memcached.yaml
:The key-value pairs in the Custom Resource spec are passedto Ansible as extra variables.
Note: The names of all variables in the spec field are converted tosnake_case by the operator before running ansible. For example,serviceAccount in the spec becomes service_account in ansible. You candisable this case conversion by setting the
snakeCaseParameters
optionto false
in your watches.yaml
. It is recommended that you perform sometype validation in Ansible on the variables to ensure that yourapplication is receiving expected input.Configure the operator’s image registry
All that remains is to build and push the operator image to the desired image registry.Your Makefile composes image tags either from values written at project initialization or from the CLI.In particular,
IMAGE_TAG_BASE
lets you define a common image registry, namespace, and partial namefor all your image tags. Update this to another registry and/or namespace if the current value is incorrect.Afterwards you can update the IMG
variable definition like so:Once done, you do not have to set
IMG
or any other image variable in the CLI. The following command willbuild and push an operator image tagged as example.com/memcached-operator:v0.0.1
to Docker Hub:Run the Operator
There are three ways to run the operator:
- As Go program outside a cluster
- As a Deployment inside a Kubernetes cluster
- Managed by the Operator Lifecycle Manager (OLM) in bundle format
1. Run locally outside the cluster
Execute the following command, which install your CRDs and run the manager locally:
2. Run as a Deployment inside the cluster
By default, a new namespace is created with name
<project-name>-system
, ex. memcached-operator-system
, and will be used for the deployment.Run the following to deploy the operator. This will also install the RBAC manifests from
config/rbac
.![Ansible commands cheat sheet pdf Ansible commands cheat sheet pdf](/uploads/1/1/7/7/117726314/607439011.png)
Verify that the memcached-operator is up and running:
3. Deploy your Operator with OLM
First, install OLM:
Bundle your operator, then build and push the bundle image. The
bundle
target generates a bundlein the bundle
directory containing manifests and metadata defining your operator.bundle-build
and bundle-push
build and push a bundle image defined by bundle.Dockerfile
.Finally, run your bundle. If your bundle image is hosted in a registry that is private and/orhas a custom CA, these configuration steps must be complete.
Check out the docs for a deep dive into
operator-sdk
's OLM integration.Create a Memcached CR
Update the sample Memcached CR manifest at
config/samples/cache_v1alpha1_memcached.yaml
and define the spec
as the following:Create the CR:
Ensure that the memcached operator creates the deployment for the sample CR with the correct size:
Check the pods and CR status to confirm the status is updated with the memcached pod names:
Update the size
Update
config/samples/cache_v1alpha1_memcached.yaml
to change the spec.size
field in the Memcached CR from 3 to 5:Confirm that the operator changes the deployment size:
Cleanup
Run the following to delete all deployed resources:
Next Steps
We recommend reading through the our Ansible development sectionfor tips and tricks, including how to run the operator locally.
In this tutorial, the scaffolded
watches.yaml
could be used as-is, buthas additional optional features. See watches reference.For brevity, some of the scaffolded files were left out of this guide.See Scaffolding Reference
This example built a namespaced scope operator, but Ansible operatorscan also be used with cluster-wide scope.
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 guide.
Last modified April 12, 2021: `run bundle(-upgrade)`: configure registry pod with root certificate secret (#4703) (7e43b470)
Note
This module is part of
ansible-base
and included in all Ansibleinstallations. In most cases, you can use the short module namecommand even without specifying the collections:
keyword.Despite that, we recommend you use the FQCN for easy linking to the moduledocumentation and to avoid conflicting with other collections that may havethe same module name.- The
command
module takes the command name followed by a list of space-delimited arguments. - The given command will be executed on all selected nodes.
- The command(s) will not be processed through the shell, so variables like
$HOSTNAME
and operations like'*'
,'<'
,'>'
,'|'
,';'
and'&'
will not work. Use the ansible.builtin.shell module if you need these features. - To create
command
tasks that are easier to read than the ones using space-delimited arguments, pass parameters using theargs
task keyword or usecmd
parameter. - Either a free form command or
cmd
Who runs larry the cat twitter. parameter is required, see the examples. - For Windows targets, use the ansible.windows.win_command module instead.
Note
Ansible Commands Cheat Sheet
This module has a corresponding action plugin.
Parameter | Choices/Defaults | Comments |
---|---|---|
argv list / elements=string | Passes the command as a list rather than a string. Use argv to avoid quoting values that would otherwise be interpreted incorrectly (for example 'user name').Only the string (free form) or the list (argv) form can be provided, not both. One or the other must be provided. | |
chdir path | Change into this directory before running the command. | |
cmd string | ||
creates | A filename or (since 2.0) glob pattern. If a matching file already exists, this step will not be run. | |
free_form string | The command module takes a free form string as a command to run. | |
removes added in 0.8 of ansible.builtin | A filename or (since 2.0) glob pattern. If a matching file exists, this step will be run. | |
stdin string | Set the stdin of the command directly to the specified value. | |
stdin_add_newline boolean |
| |
strip_empty_ends added in 2.8 of ansible.builtin |
| Strip empty lines from the end of stdout/stderr in result. |
warn boolean |
|
Note
- If you want to run a command through the shell (say you are using
<
,>
,|
, and so on), you actually want the ansible.builtin.shell module instead. Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to use thecommand
module when possible. creates
,removes
, andchdir
Knives out daniel craig. can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this.- Check mode is supported when passing
creates
orremoves
. If running in check mode and either of these are specified, the module will check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped. - The
executable
parameter is removed since version 2.4. If you have a need for this parameter, use the ansible.builtin.shell module instead. - For Windows targets, use the ansible.windows.win_command module instead.
- For rebooting systems, use the ansible.builtin.reboot or ansible.windows.win_reboot module.
See also
Ansible Commands Cheat Sheet 2019
The official documentation on the ansible.builtin.raw module.
The official documentation on the ansible.builtin.script module.
The official documentation on the ansible.builtin.shell module.
Ansible Commands Cheat Sheet
Ansible Commands Cheat Sheet Excel
The official documentation on the ansible.windows.win_command module.
Common return values are documented here, the following are the fields unique to this module:
Ansible Ad-hoc Commands Cheat Sheet Pdf
Key | Returned | Description |
---|---|---|
cmd list / elements=string | always | Sample: |
delta | always | The command execution delta time. 0:00:00.001529 |
end string | always | Sample: |
msg | always | changed True |
rc integer | always | |
start | always | The command execution start time. 2017-09-29 22:03:48.083128 |
stderr string | always | Sample: |
stderr_lines | always | The command standard error split in lines. [{'u'ls cannot access foo': 'No such file or directory'}, 'u'ls …'] |
stdout string | always | Sample: Clustering node [email protected] with [email protected] … |
stdout_lines list / elements=string | always | Sample: ['u'Clustering node [email protected] with [email protected] …'] |