From 5472f93a5a39bc817affc7ac71e079d16ff4c22c Mon Sep 17 00:00:00 2001
From: Robin Gierse <robin.gierse@tribe29.com>
Date: Fri, 16 Feb 2024 11:27:19 -0500
Subject: [PATCH] Add dedicated README for lookup plugins.

---
 README.md                |  1 +
 plugins/lookup/README.md | 57 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 plugins/lookup/README.md

diff --git a/README.md b/README.md
index 498975512..4d2772925 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ Name | Description
 
 ### Lookup plugins
 Click on the lookup plugin name below, to get detailed documentation about it.
+For more in-depth documentation, see [this README](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/lookup/README.md).
 
 Name | Description | Tests
 --- | --- | ---
diff --git a/plugins/lookup/README.md b/plugins/lookup/README.md
new file mode 100644
index 000000000..c5b855619
--- /dev/null
+++ b/plugins/lookup/README.md
@@ -0,0 +1,57 @@
+# Lookup Plugins
+
+## Using variables for Lookup plugins
+It is possible to set variables for authentication globally for lookup plugins.
+This way, they do not need to be provided at task level.
+
+### Method 1: Environment variables
+```bash
+export ANSIBLE_LOOKUP_CHECKMK_SERVER_URL="https://myserver"
+export ANSIBLE_LOOKUP_CHECKMK_SITE=mysite
+export ANSIBLE_LOOKUP_AUTOMATION_USER=automation
+export ANSIBLE_LOOKUP_AUTOMATION_SECRET=mysecret
+export ANSIBLE_LOOKUP_VALIDATE_CERTS=False
+```
+
+### Method 2: In `ansible.cfg`
+```ini
+[checkmk_lookup]
+server_url = https://myserver
+site = mysite
+automation_user = automation
+automation_secret = mysecret
+validate_certs = False
+
+```
+
+### Method 3: In playbooks or the inventory
+```yaml
+- name: My Task
+  hosts: localhost
+  gather_facts: false
+  vars:
+    ansible_lookup_checkmk_server_url: "https://myserver"
+    ansible_lookup_checkmk_site: "mysite"
+    ansible_lookup_automation_user: "automation"
+    ansible_lookup_automation_secret: "mysecret"
+    ansible_lookup_validate_certs: false
+
+  tasks:
+    - name: Get the attributes of myhost
+      ansible.builtin.debug:
+        msg: "Attributes of myhost: {{ attributes }}"
+      vars:
+        attributes: "{{ lookup('checkmk.general.host', 'myhost', effective_attributes=True) }}"
+```
+
+### Example
+The following task will work, if one of the above methods has been applied.
+```yaml
+- name: My Task
+  tasks:
+    - name: Get the attributes of myhost
+      ansible.builtin.debug:
+        msg: "Attributes of myhost: {{ attributes }}"
+      vars:
+        attributes: "{{ lookup('checkmk.general.host', 'myhost', effective_attributes=True) }}"
+```