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.

Included content

Click on the name of a plugin or module to view that content's documentation:

Connection Plugins:
- kubectl
Filter Plugins:
- k8s_config_resource_name
Inventory Source:
- k8s
- openshift
Lookup Plugins:
- k8s
Modules:
- k8s
- k8s_auth
- k8s_info
- k8s_scale
- k8s_service

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: 1.0.0

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: Get a list of all pods in the kube-system namespace.
      k8s_info:
        kind: Pod
        namespace: kube-system
      register: system_pods

    - name: Display pod information for pods in kube-system namespace.
      debug:
        var: system_pods.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.

The tests directory contains configuration for running sanity and integration tests using ansible-test.

You can run the collection's test suites with the commands:

ansible-test sanity --docker -v --color
ansible-test integration --docker -v --color

More Information

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.

License

GNU General Public License v3.0 or later

See LICENCE to see the full text.

3.9 KiB Raw Blame History