Merge pull request #490 from mattbator/main

Initial pattern docs for ansible-edge-gitops-kasten

Author: mhjacks

.wordlist.txt

@@ -14,7 +14,7 @@ additionalimages
 addon
 addons
 addr
-addr
+addr
 adoc
 ae
 aeg
@@ -502,6 +502,8 @@ kafkatopic
 kafkatopics
 kam
 kamelet
+kasten
+kastendr
 keycloak
 keypair
 keypairs
@@ -1025,6 +1027,7 @@ vdjtkgams
 vdvkgdtuxkeqf
 vectordb
 vectorized
+veeam
 vfio
 vhjpkievife
 virtualmachine

content/patterns/ansible-edge-gitops-kasten/_index.md

@@ -0,0 +1,77 @@
+---
+title: Ansible Edge GitOps with Veeam Kasten
+date: 2024-10-28
+tier: sandbox
+summary: This pattern uses OpenShift Virtualization to simulate an edge environment for VMs, protected by Veeam Kasten.
+rh_products:
+- Red Hat OpenShift Container Platform
+- Red Hat Ansible Automation Platform
+- Red Hat OpenShift Virtualization
+- Red Hat Enterprise Linux
+- Red Hat OpenShift Data Foundation
+other_products:
+- Veeam Kasten
+industries:
+- Chemical
+aliases: /ansible-edge-gitops-kasten/
+pattern_logo: veeam-kasten.png
+links:
+  install: getting-started
+  help: https://groups.google.com/g/validatedpatterns
+  bugs: https://github.com/validatedpatterns/ansible-edge-gitops/issues
+# ci: aegitops
+---
+
+# Ansible Edge GitOps with Veeam Kasten
+
+## Background
+
+Organizations are interested in accelerating their deployment speeds and improving delivery quality in their Edge environments, where many devices may not fully or even partially embrace the GitOps philosophy. Further, there are VMs and other devices that can and should be managed with Ansible. This pattern explores some of the possibilities of using an OpenShift-based Ansible Automated Platform deployment and managing edge devices, based on work done with a partner in the Chemical space.
+
+This pattern uses **OpenShift Virtualization** (the productization of KubeVirt) to provision VMs alongside Kubernetes-native workloads on the cluster. As VMs are inherently stateful workloads, a GitOps approach alone is not sufficient to recover an environment in the event of accidental data loss, malware attack, or infrastructure failure - especially in edge environments where infrastructure may be less resilient or subject to harsh environments. This example extends the standard [Ansible Edge GitOps pattern](https://validatedpatterns.io/patterns/ansible-edge-gitops/) to include automated deployment and configuration of [Veeam Kasten](https://www.veeam.com/products/cloud/kubernetes-data-protection.html), the #1 Kubernetes data protection and mobility solution.
+
+### Solution elements
+
+- How to use a GitOps approach to manage virtual machines, either in public clouds (limited to AWS for technical reasons) or on-prem OpenShift installations
+- How to integrate AAP into OpenShift
+- How to manage Edge devices using AAP hosted in OpenShift
+- How to protect OpenShift Virtualzation VMs
+
+### Red Hat Technologies
+
+- Red Hat OpenShift Container Platform (Kubernetes)
+- Red Hat Ansible Automation Platform (formerly known as "Ansible Tower")
+- Red Hat OpenShift GitOps (ArgoCD)
+- OpenShift Virtualization (KubeVirt)
+- Red Hat Enterprise Linux 8
+
+### Other Technologies this Pattern Uses
+
+- Veeam Kasten
+- Hashicorp Vault
+- External Secrets Operator
+- Inductive Automation Ignition
+
+## Architecture
+
+Similar to other patterns, this pattern starts with a central management hub, which hosts the AAP and Vault components. Veeam Kasten is deployed on each cluster it protects, providing a self-contained solution ideal for edge deployments without dependencies on external infrastructure or SaaS management plane.
+
+### Logical architecture
+
+![Ansible-Edge-Gitops-Architecture](/images/ansible-edge-gitops/ansible-edge-gitops-arch.png)
+
+### Physical Architecture
+
+![Ansible-Edge-GitOps-Physical-Architecture](/images/ansible-edge-gitops-kasten/aeg-arch-schematic.png)
+
+## Other Presentations Featuring this Pattern
+
+### Registration Required
+
+[![Ansible-Automates-June-2022-Deck](/images/ansible-edge-gitops/automates-june-2022-deck-thumb.png)](https://tracks.redhat.com/c/validated-patterns_i?x=5wCWYS&lx=lT1ZfK)
+
+[![Ansible-Automates-June-2022-Video](/images/ansible-edge-gitops/automates-june-2022-video-thumb.png)](https://tracks.redhat.com/c/preview-42?x=5wCWYS&lx=lT1ZfK)
+
+## What's Next
+
+- [Getting Started: Deploying and Validating the Pattern](getting-started)

content/patterns/ansible-edge-gitops-kasten/ansible-automation-platform.md

@@ -0,0 +1,193 @@
+---
+title: Ansible Automation Platform
+weight: 40
+aliases: /ansible-edge-gitops-kasten/ansible-automation-platform/
+---
+
+# Ansible Automation Platform
+
+# How it's installed
+
+See the installation details [here](/patterns/ansible-edge-gitops/installation-details/#ansible-automation-platform-aap-formerly-known-as-ansible-tower).
+
+# How to Log In
+
+The default login user is `admin` and the password is generated randomly at install time; you will need the password to login in to the AAP interface. You do not have to log in to the interface - the pattern will configure the AAP instance; the pattern retrieves the password using the same technique as the `ansible_get_credentials.sh` script described below. If you want to inspect the AAP instance, or change any aspects of its configuration, there are two ways to login and look at it. Both mechanisms are equivalent; you get the same password to the same instance using either technique.
+
+## Via the OpenShift Console
+
+In the OpenShift console, navigate to Workloads > Secrets and select the "ansible-automation-platform" project if you want to limit the number of Secrets you can see.
+
+[![secrets-navigation](/images/ansible-edge-gitops/ocp-console-secrets-aap-admin-password.png)](/images/ansible-edge-gitops/ocp-console-secrets-aap-admin-password.png)
+
+The Secret you are looking for is in the `ansible-automation-platform` project and is named `controller-admin-password`. If you click on it, you can see the Data.password field. It is shown revealed below to show that it is the same as what is shown by the script method of retrieving it below:
+
+[![secrets-detail](/images/ansible-edge-gitops/ocp-console-aap-admin-password-detail.png)](/images/ansible-edge-gitops/ocp-console-aap-admin-password-detail.png)
+
+## Via [ansible_get_credentials.sh](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/scripts/ansible_get_credentials.sh)
+
+With your KUBECONFIG set, you can run `./scripts/ansible-get-credentials.sh` from your top-level pattern directory. This will use your OpenShift cluster admin credentials to retrieve the URL for your Ansible Automation Platform instance, as well as the password for its `admin` user, which is auto-generated by the AAP operator by default. The output of the command looks like this (your password will be different):
+
+```text
+./scripts/ansible_get_credentials.sh
+[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match
+'all'
+
+PLAY [Install manifest on AAP controller] ******************************************************************************
+
+TASK [Retrieve API hostname for AAP] ***********************************************************************************
+ok: [localhost]
+
+TASK [Set ansible_host] ************************************************************************************************
+ok: [localhost]
+
+TASK [Retrieve admin password for AAP] *********************************************************************************
+ok: [localhost]
+
+TASK [Set admin_password fact] *****************************************************************************************
+ok: [localhost]
+
+TASK [Report AAP Endpoint] *********************************************************************************************
+ok: [localhost] => {
+    "msg": "AAP Endpoint: https://controller-ansible-automation-platform.apps.mhjacks-aeg.blueprints.rhecoeng.com"
+}
+
+TASK [Report AAP User] *************************************************************************************************
+ok: [localhost] => {
+    "msg": "AAP Admin User: admin"
+}
+
+TASK [Report AAP Admin Password] ***************************************************************************************
+ok: [localhost] => {
+    "msg": "AAP Admin Password: CKollUjlir0EfrQuRrKuOJRLSQhi4a9E"
+}
+
+PLAY RECAP *************************************************************************************************************
+localhost                  : ok=7    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
+```
+
+# Pattern AAP Configuration Details
+
+In this section, we describe the details of the AAP configuration we apply as part of installing the pattern. All of the configuration discussed in this section is applied by the [ansible_load_controller.sh](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/scripts/ansible_load_controller.sh) script.
+
+## Loading a Manifest
+
+After validating that AAP is ready to be configured, the first thing the script does is to install the manifest you specify in the `values-secret.yaml` file in the `files.manifest` setting. The value of this setting is expected to be a fully-pathed file that represents a Red Hat Satellite manifest file with a valid entitlement for AAP. The *only* thing this manifest is used for is entitling AAP.
+
+Instructions for creating a suitable manifest file can be found [here](https://www.redhat.com/en/blog/how-create-and-use-red-hat-satellite-manifest).
+
+While it is absolutely possible to entitle AAP via a username/password on first login, the automated mechanisms for entitling only support manifests, that is the technique the pattern uses.
+
+## Organizations
+
+The pattern installs an Organization called `HMI Demo` is installed. This makes it a bit easier to separate what the pattern is doing versus the default configuration of AAP. The other resources created in AAP as part of the load process are associated with this Organization.
+
+## Credential Types (and their Credentials)
+
+### Kubeconfig (Kubeconfig)
+
+The Kubeconfig credential is for holding the OpenShift cluster admin kubeconfig file. This is used to query the `edge-gitops-vms` namespace for running VM instances. Since the kubeconfig is necessary for installing the pattern and must be available when the load script is running, the load script pulls it into an AAP secret and stores it for later use (and calls it `Kubeconfig`).
+
+The template for creating the Credential Type was taken from [here](https://blog.networktocode.com/post/kubernetes-collection-ansible/).
+
+### RHSMcredential (rhsm_credential)
+
+This credential is required to register the RHEL VMs and configure them for Kiosk mode. The registration process allows them to install packages from the Red Hat Content Delivery Network.
+
+### Machine (kiosk-private-key)
+
+This is a standard AAP Machine type credential. `kiosk-private-key` is created with the username and private key from your `values-secret.yaml` file in the `kiosk-ssh.username` and `kiosk-ssh.privatekey` fields.
+
+### KioskExtraParams (kiosk_container_extra_params)
+
+This CredentialType is considered "secret" because it includes the admin login password for the Ignition application. This passed to the provisioning playbook(s) as extra_vars.
+
+## Inventory
+
+The pattern installs an Inventory (HMI Demo), but no inventory sources. This is due to the way that OpenShift Virtualization provides access to virtual machines. The IP address associated with the SSH service that a given VM is running is associated with the Service object on the VM. This is not the way the Kubernetes inventory plugin expects to work. So to make inventory dynamic, we are instead using a play to discover VMs and add them to inventory "on the fly". What is unusual about DNS inside a Kubernetes cluster is that resources outside the namespace must use the cluster FQDN - which is `resource-name.resource-namespace.svc`.
+
+It is also possible to define a static inventory - an example of how this would like is preserved in the pattern repository as [hosts](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/inventory/hosts).
+
+A standard dynamic inventory script is available [here](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/inventory/openshift_cluster.yml). This will retrieve the object names, but it will not (currently) map the FQDN properly. Because of this limitation, we moved to using the inventory pre-play method.
+
+## Templates (key playbooks in the pattern)
+
+### [Dynamic Provision Kiosk Playbook](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/dynamic_kiosk_provision.yml)
+
+This combines all three key workflows in this pattern:
+
+* Dynamic inventory (inventory preplay)
+* Kiosk Mode
+* Podman Playbook
+
+It is safe to run multiple times on the same system. It is run on a schedule, every 10 minutes, to demonstrate this.
+
+### [Kiosk Mode Playbook](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/kiosk_playbook.yml)
+
+This playbook runs the [kiosk_mode role](/patterns/ansible-edge-gitops/ansible-automation-platform/#roles-included-in-the-pattern).
+
+### [Podman Playbook](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/podman_playbook.yml)
+
+This playbook runs the [container_lifecycle role](/patterns/ansible-edge-gitops/ansible-automation-platform/#roles-included-in-the-pattern) with overrides suitable for the Ignition application container.
+
+### [Ping Playbook](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/ping.yml)
+
+This playbook is for testing basic connectivity - making sure that you can reach the nodes you wish to manage, and that the credentials you have given will work on them. It will not change anything on the VMs - just gather facts from them (which requires elevating to root).
+
+## Schedules
+
+### Update Project AEG GitOps
+
+This job runs every 5 minutes to update the GitOps repository associated with the project. This is necessary when any of the Ansible code (for example, the playbooks or roles associated with the pattern) changes, so that the new code is available to the AAP instance.
+
+### Dynamic Provision Kiosk Playbook
+
+This job runs every 10 minutes to provision and configure any kiosks it finds to run the Ignition application in a podman container, and configure firefox in kiosk mode to display that application. The playbook is designed to be idempotent, so it is safe to run multiple times on the same targets; it will not make user-visible changes to those targets unless it must.
+
+This playbook combines the [inventory_preplay](/patterns/ansible-edge-gitops/ansible-automation-platform/#extra-playbooks-in-the-pattern) and the [Provision Kiosk Playbook](/patterns/ansible-edge-gitops/ansible-automation-platform/#extra-playbooks-in-the-pattern).
+
+## Execution Environment
+
+The pattern includes an execution environment definition that can be found [here](https://github.com/validatedpatterns/ansible-edge-gitops/tree/main/ansible/execution_environment).
+
+The execution environment includes some additional collections beyond what is provided in the Default execution environment, including:
+
+* [fedora.linux_system_roles](https://linux-system-roles.github.io/)
+* [containers.podman](https://galaxy.ansible.com/containers/podman)
+* [community.okd](https://docs.ansible.com/ansible/latest/collections/community/okd/index.html)
+
+The execution environment definition is provided if you want to customize or change it; if so, you should also change the Execution Environment attributes of the Templates (in the [load script](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/scripts/ansible_load_controller.sh), those attributes are set by the variables `aap_execution_environment` and `aap_execution_environment_image`).
+
+## Roles included in the pattern
+
+### [kiosk_mode](https://github.com/validatedpatterns/ansible-edge-gitops/tree/main/ansible/roles/kiosk_mode)
+
+This role is responsible does the following:
+
+* RHEL node registration
+* Installation of GUI packages
+* Installation of Firefox
+* Configuration of Firefox kiosk mode
+
+### [container_lifecycle](https://github.com/validatedpatterns/ansible-edge-gitops/tree/main/ansible/roles/container_lifecycle)
+
+This role is responsible for:
+
+* Downloading and running a podman image on the system (and configure it to auto-update)
+* Setting the container up to run at boot time
+* Passing any other runtime arguments to the container. In this container's case, that includes specifying an admin password override.
+
+## Extra Playbooks in the Pattern
+
+### [inventory_preplay.yml](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/inventory_preplay.yml)
+
+This playbook is designed to be included in other plays; its purpose is to discover the desired inventory and add those hosts to inventory at runtime. It uses a kubernetes query via the cluster-admin kube config file.
+
+### [Provision Kiosk Playbook](https://github.com/validatedpatterns/ansible-edge-gitops/blob/main/ansible/provision_kiosk.yml)
+
+This does the work of provisioning the kiosk, which configures kiosk mode, and also installs Ignition and configures it to start at boot. It runs the [kiosk_mode](/patterns/ansible-edge-gitops/ansible-automation-platform/#roles-included-in-the-pattern) and [container_lifecycle](/patterns/ansible-edge-gitops/ansible-automation-platform/#roles-included-in-the-pattern) roles.
+
+# Next Steps
+
+## [Help & Feedback](https://groups.google.com/g/validatedpatterns)
+## [Report Bugs](https://github.com/validatedpatterns/ansible-edge-gitops/issues)