From 0cd29010f64dad3df38f17a32a1d591071e46a23 Mon Sep 17 00:00:00 2001
From: Jeff Geerling <geerlingguy@mac.com>
Date: Fri, 31 Jan 2020 15:00:00 -0600
Subject: [PATCH] Fixes #3: Add a README with relevant documentation links and
 usage instructions.

---
 README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 78 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 10ba7282..9e222530 100644
--- a/README.md
+++ b/README.md
@@ -4,13 +4,87 @@
 
 This repo hosts the `community.kubernetes` Ansible Collection.
 
-As this is an independent Collection, it can be released on its own release cadence.
+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.
 
-## Notes
+## Included content
 
-*WARNING* This is Work in progress
+Click on the name of a plugin or module to view that content's documentation:
 
-For more information see `#ansible-community` on Freenode IRC, or the [Kubernetes Working Group](https://github.com/ansible/community/wiki/Kubernetes) Community wiki page.
+  - **Connection Plugins**:
+    - [kubectl](https://docs.ansible.com/ansible/latest/plugins/connection/kubectl.html)
+  - **Filter Plugins**:
+    - [k8s_config_resource_name](https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html#kubernetes-filters)
+  - **Inventory Source**:
+    - [k8s](https://docs.ansible.com/ansible/latest/plugins/inventory/k8s.html)
+    - [openshift](https://docs.ansible.com/ansible/latest/plugins/inventory/openshift.html)
+  - **Lookup Plugins**:
+    - [k8s](https://docs.ansible.com/ansible/latest/plugins/lookup/k8s.html)
+  - **Modules**:
+    - [k8s](https://docs.ansible.com/ansible/latest/modules/k8s_module.html)
+    - [k8s_auth](https://docs.ansible.com/ansible/latest/modules/k8s_auth_module.html)
+    - [k8s_info](https://docs.ansible.com/ansible/latest/modules/k8s_info_module.html)
+    - [k8s_scale](https://docs.ansible.com/ansible/latest/modules/k8s_scale_module.html)
+    - [k8s_service](https://docs.ansible.com/ansible/latest/modules/k8s_service_module.html)
+
+## 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:
+
+```yaml
+---
+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:
+
+```yaml
+---
+- 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`](https://docs.ansible.com/ansible/latest/reference_appendices/config.html#collections-paths), and work on it there.
+
+The `tests` directory contains configuration for running sanity and integration tests using [`ansible-test`](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html).
+
+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](https://github.com/ansible/community/wiki/Kubernetes) Community wiki page.
 
 ## License