Kubernetes Collection for Ansible
This repo hosts the
community.kubernetes Ansible Collection.
The collection includes a variety of Ansible content to help automate the management of applications in Kubernetes and OpenShift clusters, as well as the provisioning and maintenance of clusters themselves.
Click on the name of a plugin or module to view that content's documentation:
- Connection Plugins:
- Filter Plugins:
- Inventory Source:
- Lookup Plugins:
Installation and Usage
Installing the Collection from Ansible Galaxy
Before using the Kuberentes collection, you need to install it with the Ansible Galaxy CLI:
ansible-galaxy collection install community.kubernetes
You can also include it in a
requirements.yml file and install it via
ansible-galaxy collection install -r requirements.yml, using the format:
--- collections: - name: community.kubernetes version: 0.9.0
Installing the OpenShift Python Library
Content in this collection requires the OpenShift Python client to interact with Kubernetes' APIs. You can install it with:
pip3 install openshift
Using modules from the Kubernetes Collection in your playbooks
You can either call modules by their Fully Qualified Collection Namespace (FQCN), like
community.kubernetes.k8s_info, or you can call modules by their short name if you list the
community.kubernetes collection in the playbook's
collections, like so:
--- - hosts: localhost gather_facts: false connection: local collections: - community.kubernetes tasks: - name: Ensure the myapp Namespace exists. k8s: api_version: v1 kind: Namespace name: myapp state: present - name: Ensure the myapp Service exists in the myapp Namespace. k8s: state: present definition: apiVersion: v1 kind: Service metadata: name: myapp namespace: myapp spec: type: LoadBalancer ports: - port: 8080 targetPort: 8080 selector: app: myapp - name: Get a list of all Services in the myapp namespace. k8s_info: kind: Service namespace: myapp register: myapp_services - name: Display number of Services in the myapp namespace. debug: var: myapp_services.resources | count
For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README.
Testing and Development
If you want to develop new content for this collection or improve what's already here, the easiest way to work on the collection is to clone it into one of the configured
COLLECTIONS_PATHS, and work on it there.
tests directory contains configuration for running sanity and integration tests using
You can run the collection's test suites with the commands:
ansible-test sanity --docker -v --color ansible-test integration --docker -v --color
There are also integration tests in the
molecule directory which are meant to be run against a local Kubernetes cluster, e.g. using KinD or Minikube. To run the tests, set up a local cluster, then run Molecule:
kind create cluster molecule test
Publishing New Versions
The current process for publishing new versions of the Kubernetes Collection is manual, and requires a user who has access to the
community.kubernetes namespace on Ansible Galaxy to publish the build artifact.
CHANGELOG.mdcontains all the latest changes.
galaxy.ymland this README's
requirements.ymlexample with the new
versionfor the collection.
Tag the version in Git and push to GitHub.
Run the following commands to build and release the new version on Galaxy:
ansible-galaxy collection build ansible-galaxy collection publish ./community-kubernetes-$VERSION_HERE.tar.gz
After the version is published, verify it exists on the Kubernetes Collection Galaxy page.
For more information about Ansible's Kubernetes integration, join the
#ansible-community channel on Freenode IRC, and browse the resources in the Kubernetes Working Group Community wiki page.
GNU General Public License v3.0 or later
See LICENCE to see the full text.