Merge pull request ansible#1951 from djdanielsson/devel

adding config as code exercises and deck

exercises/ansible_config_as_code/0-setup/README.md

@@ -0,0 +1,174 @@
+# Intro
+
+In this section we will show you step by step how to add pre commit linting to a repository. You will be able to use this on the command line to lint your code and use it in a github repository. The lab already has git repo created and cloned onto your vscode instance.
+
+## Pre Steps
+
+If you are using the Workshop, a Workshop project should be available in your VSCode for you to push to the Workshop Gitea server. Create the files in this project folder.
+
+NOTE: If when you click on the Explorer tab that looks like two pieces of paper and you see "Open Folder" click on that. In the popup window click windows-workshop/workshop_project/ (full path is: `/home/student/windows-workshop/workshop_project`) then click "ok". If prompted select the check box and "Yes, I trust the authors" option. You should now see a readme that has a typo saying Welcome to Windows Automation workshop.
+
+## Step 1
+
+Ensure that you have `pre-commit` installed on your machine. On the VScode toolbar you should see `Terminal` then in the dropdown select `New Terminal`.
+
+```console
+sudo pip3 install --upgrade pip
+sudo pip3.9 install pre-commit
+```
+
+NOTE: Normally we would suggest `dnf install pre-commit` but in this lab we will have to use pip3
+
+Next, configure pre-commit to a pre-hook action.
+
+```console
+pre-commit install
+```
+
+Further documentation for those who are interested to learn more see:
+
+- [Pre-commit installation](https://pre-commit.com/#installation)
+
+## Step 2
+
+Create a file that links to the pre-commit hooks that you want to use. In our case, some general cleanup hooks, yamllint, and ansible-lint.
+
+Create a file in this folder path `.pre-commit-config.yaml`
+
+```yaml
+---
+repos:
+  - repo: 'https://github.com/pre-commit/pre-commit-hooks'
+    rev: v4.3.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: 'https://github.com/ansible-community/ansible-lint.git'
+    rev: v6.6.1
+    hooks:
+      - id: ansible-lint
+        pass_filenames: false
+        always_run: true
+        entry: "ansible-lint"
+        args:
+          - "--profile=production"
+        additional_dependencies:
+          - "ansible-core>=2.13"
+          - "yamllint>=1.26,<2.0"
+...
+
+```
+
+Create a yaml lint file `.yamllint.yml` to hold our yaml rules.
+
+```yaml
+---
+extends: default
+
+ignore: |
+  changelogs
+  vault.yml
+rules:
+  # 80 chars should be enough, but don't fail if a line is longer
+  line-length: disable
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: -1
+  document-end:
+    present: true
+  document-start:
+    present: true
+  indentation:
+    level: error
+    # Require indentation https://redhat-cop.github.io/automation-good-practices/#_yaml_and_jinja2_syntax
+    spaces: 2
+    indent-sequences: true
+    check-multi-line-strings: false
+  truthy:
+    level: error
+    # Allow only YAML 1.2 booleans https://redhat-cop.github.io/automation-good-practices/#_yaml_and_jinja2_syntax
+    allowed-values:
+      - 'true'
+      - 'false'
+...
+
+```
+
+Further documentation for more hooks that can be added can be found here:
+
+- [pre-commit config](https://pre-commit.com/#pre-commit-configyaml---top-level)
+- [yamllint](https://yamllint.readthedocs.io/en/stable/)
+
+## Step 3
+
+To use this in github set the workflow action in a file.
+
+Create a file in this folder path `.github/workflows/pre-commit.yml`
+
+```yaml
+---
+name: Yaml and Ansible Lint
+
+on: [push, pull_request]  # yamllint disable-line rule:truthy
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+      - name: Install Collections
+        run: |
+          sudo apt install software-properties-common
+          sudo apt-add-repository --yes --update ppa:ansible/ansible
+          sudo apt install ansible
+      - uses: pre-commit/[email protected]
+...
+
+```
+
+Further documentation for more hooks that can be added can be found here:
+
+- [Supported hooks](https://pre-commit.com/hooks.html)
+
+## Step 4
+
+Now lets create some git files.
+
+Create a file `.gitignore` which we will use to tell git to not include some files.
+
+```text
+.password
+ansible.cfg
+ansible-navigator.log
+*.json
+```
+
+Next let's create a `.gitattributes` file
+
+```text
+*.yml linguist-detectable
+*.yaml linguist-detectable
+```
+
+Further documentation for more hooks that can be added can be found here:
+
+- [git ignore](https://git-scm.com/docs/gitignore)
+- [git attributes](https://git-scm.com/docs/gitattributes)
+- [github linguist](https://github.com/github/linguist/blob/master/docs/how-linguist-works.md)
+
+## Step 5
+
+Commit your current work so far. (note we won't mention it again but you should commit and push at the end of each section)
+
+```console
+git add .
+git commit -am "task0 complete"
+git push origin master
+```
+
+NOTE: It is likely you will get a failed commit the first attempt due to end of line auto fixes taking place, if this happens just run the commit again and everything should be green.
+
+NOTE: also if you get an error about credential helper run `git config --global --unset credential.helper` and then do your commit again.
+
+[next task](../1-ee/README.md)

exercises/ansible_config_as_code/1-ee/README.md

@@ -0,0 +1,215 @@
+# Intro
+
+In this section we will show you step by step how to build an Execution Environment (EE) from code. You will also be publishing this EE to your own private automation hub which you will use in the rest of the tasks.
+
+## Step 1
+
+Ensure that you have `ansible-core`, `ansible-lint`, and `ansible-builder`, and `podman` installed on your machine.
+
+```console
+sudo dnf install ansible-core ansible-lint ansible-builder podman
+```
+
+Further documentation for those who are interested to learn more see:
+
+- [upgrading from ansible to ansible-core](https://access.redhat.com/discussions/6962395)
+- [using pip (non supported upstream version)](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
+
+## Step 2
+
+Install our ee_utilities collection and containers.podman using `ansible-galaxy` command.
+
+```console
+ansible-galaxy collection install infra.ee_utilities containers.podman community.general
+```
+
+Further documentation for those who are interested to learn more see:
+
+- [installing collections using cli](https://docs.ansible.com/ansible/devel/user_guide/collections_using.html#collections)
+- [using collections in AAP](https://docs.ansible.com/ansible-tower/latest/html/userguide/projects.html#collections-support)
+
+## Step 3
+
+### **In the next few steps pay attention to the folder paths and make sure to put the files in the correct folders**
+
+Set the variables to be used in the collections for use. These include hosts, usernames, and other variables that are reused in each role.
+
+Create a file in this folder path `group_vars/all/auth.yml`
+
+{% raw %}
+
+```yaml
+---
+controller_hostname: "{{ controller_host | default(groups['automationcontroller'][0]) }}"
+controller_username: "{{ controller_user | default('admin') }}"
+controller_password: "{{ controller_pass }}"
+controller_validate_certs: false
+
+ah_host: "{{ ah_hostname | default(groups['automationhub'][0]) }}"
+ah_username: "{{ ah_user | default('admin') }}"
+ah_password: "{{ ah_pass }}"
+ah_path_prefix: 'galaxy'  # this is for private automation hub
+ah_validate_certs: false
+
+ee_registry_username: "{{ ah_username }}"
+ee_registry_password: "{{ ah_password }}"
+ee_registry_dest: "{{ ah_host }}"
+...
+
+```
+
+{% endraw %}
+
+Further documentation for those who are interested to learn more see:
+
+- [more about group_vars](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#organizing-host-and-group-variables)
+
+## Step 4
+
+Create your inventory file `inventory.yml`, **YOU WILL NEED TO FILL THESE IN** copy in the servers replacing lines 77, 81, and 85.
+
+```yaml
+---
+all:
+  children:
+    automationcontroller:
+      hosts:
+        HOST_HERE:
+
+    automationhub:
+      hosts:
+        HOST_HERE:
+
+    builder:
+      hosts:
+        VSCODE_HOST:
+...
+
+```
+
+NOTE: These are hostnames do not have 'https://' or things will fail
+
+Further documentation for those who are interested to learn more see:
+
+- [more about inventories](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#inventory-basics-formats-hosts-and-groups)
+- [how to use this source in AAP](https://docs.ansible.com/ansible-tower/latest/html/userguide/inventories.html#add-source)
+
+## Step 5
+
+Create a vault file `vault.yml` and **YOU WILL NEED TO FILL THESE IN** with the correct passwords for each variable. Currently they are set to the description of what you should be updating them too.
+
+{% raw %}
+
+```yaml
+---
+vault_pass: 'the password to decrypt this vault'
+machine_pass: 'password for root user on hub'
+controller_pass: 'account pass for controller'
+ah_pass: 'hub admin account pass'
+controller_api_user_pass: 'this will create and use this password can be generated'
+ah_token_password: 'this will create and use this password can be generated'
+student_account: 'this is the account under Git Access on your workbench information page, example: student2'
+...
+
+```
+
+NOTE: the easiest way to do this is have all passwords be the provided password.
+
+{% endraw %}
+
+Create a `.password` file **We do not recommend you do this outside of lab environment** put your generated password in this file. Even though we are not committing this file into git because we have it in our ignore list, we do not recommend putting passwords in plain text ever, this is just to simplify/speed up the lab.
+
+```text
+Your_Generated_Password_In_.password_File
+```
+
+Create an `ansible.cfg` file to point to the .password file.
+
+```ini
+[defaults]
+vault_password_file=.password
+```
+
+Encrypt vault with the password in the .password file
+
+```console
+ansible-vault encrypt vault.yml
+```
+
+Further documentation for those who are interested to learn more see:
+
+- [ansible vaults](https://docs.ansible.com/ansible/latest/user_guide/vault.html)
+- [vault with navigator](https://ansible-navigator.readthedocs.io/en/latest/faq/#how-can-i-use-a-vault-password-with-ansible-navigator)
+
+## Step 6
+
+Create a new playbook called `playbooks/build_ee.yml` and make the hosts use the group builder (which for this lab we are using automation hub, see note) and turn gather_facts on. Then add include role infra.ee_utilities.ee_builder
+
+Note: this we would normally suggest being a small cli only server for deploying config as code and running installer/upgrades for AAP
+
+```yaml
+---
+- name: Playbook to configure execution environments
+  hosts: builder
+  gather_facts: true
+  vars_files:
+    - "../vault.yml"
+  tasks:
+    - name: Include ee_builder role
+      ansible.builtin.include_role:
+        name: infra.ee_utilities.ee_builder
+...
+
+```
+
+Further documentation for those who are interested to learn more see:
+
+- [include vs import](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/include_role_module.html)
+- [ee_builder role](https://github.com/redhat-cop/ee_utilities/tree/main/roles/ee_builder)
+
+## Step 7
+
+Create a file `group_vars/all/ah_ee_list.yml` where we will create a list called `ee_list` that has 4 variables per item which are:
+
+- `name` this is required and will be what the EE image will be called
+- `bindep` this is any system packages that would be needed
+- `python` these are any python modules that need to be added through pip (excluding ansible)
+- `collections` any collections that you would like to be built into your EE image
+
+which the role will loop over and for each item in this list it will create and publish an EE using the provided variables.
+
+```yaml
+---
+ee_list:
+  - name: "config_as_code"
+    collections:
+      - name: infra.controller_configuration
+      - name: infra.ah_configuration
+      - name: infra.ee_utilities
+      - name: infra.aap_utilities
+      - name: awx.awx
+
+ee_image_push: true
+ee_prune_images: false
+ee_create_ansible_config: false
+...
+```
+
+Further documentation for those who are interested to learn more see:
+
+- [YAML lists and more](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html)
+- [builder role documentation](https://github.com/redhat-cop/ee_utilities/blob/main/roles/ee_builder/README.md#build-argument-defaults)
+
+## Step 8
+
+Run the playbook pointing to the recently created inventory file and limit the run to just builder to build your new custom EE and publish it to private automation hub.
+
+```console
+ansible-playbook -i inventory.yml -l builder playbooks/build_ee.yml
+```
+
+Further documentation for those who are interested to learn more see:
+
+- [more on ansible-playbook](https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html#ansible-playbook)
+
+[previous task](../0-setup/README.md) [next task](../2-pah/README.md)