diff --git a/README.md b/README.md index 9f20178..5b20bf1 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,38 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) # Ansible GitOps Framework (AGOF) + -* 1. [How to Use It](#HowtoUseIt) - * 1.1. [Installation](#Installation) - * 1.2. [Uninstallation](#Uninstallation) -* 2. [Entry Points](#EntryPoints) -* 3. [Using the Containerized Installer vs. The traditional one](#UsingtheContainerizedInstallervs.Thetraditionalone) - * 3.1. ["API" Install (aka "Bare")](#APIInstallakaBare) - * 3.2. ["From OS" Install](#FromOSInstall) - * 3.3. [Default Install](#DefaultInstall) - * 3.4. [Convenience Features Install (defined by options in the "default" install)](#ConvenienceFeaturesInstalldefinedbyoptionsinthedefaultinstall) -* 4. [agof_vault.yml Configuration](#agof_vault.ymlConfiguration) - * 4.1. [Common Configuration](#CommonConfiguration) - * 4.2. [Initialization Environment Configuration](#InitializationEnvironmentConfiguration) - * 4.3. [Automation Hub Specific Configuration](#AutomationHubSpecificConfiguration) - * 4.4. [AWS-Specific Configuration](#AWS-SpecificConfiguration) - * 4.5. [ImageBuilder-Specific Configuration](#ImageBuilder-SpecificConfiguration) -* 5. [What the Framework Does, Step-by-Step](#WhattheFrameworkDoesStep-by-Step) - * 5.1. [Pre-GitOps Steps](#Pre-GitOpsSteps) - * 5.1.1. [[Pre-init](init_env/pre_init_env.yml) (mandatory)](#Pre-initinit_envpre_init_env.ymlmandatory) - * 5.1.2. [[Environment Initialization](init_env/main.yml) (optional; enabled by default; `make install` entry point)](#EnvironmentInitializationinit_envmain.ymloptionalenabledbydefaultmakeinstallentrypoint) - * 5.1.3. [[Containerized Install](containerized_install/main.yml) (`make install` default)](#ContainerizedInstallcontainerized_installmain.ymlmakeinstalldefault) - * 5.1.4. [OpenShift Targets](#OpenShiftTargets) - * 5.2. [GitOps Step](#GitOpsStep) -* 6. [Acknowledgements](#Acknowledgements) + +- 1. [Prerequisites](#Prerequisites) +- 1. [How to Use It](#HowtoUseIt) + - 2.1. [Installation](#Installation) + - 2.2. [Uninstallation](#Uninstallation) +- 1. [Installation Modes](#InstallationModes) + - 3.1. ["API" Install (aka "Bare")](#APIInstallakaBare) + - 3.2. ["From OS" Install](#FromOSInstall) + - 3.3. [Default Install](#DefaultInstall) + - 3.4. [Convenience Features Install (defined by options in the "default" install)](#ConvenienceFeaturesInstalldefinedbyoptionsinthedefaultinstall) +- 1. [agof_vault.yml Configuration](#agof_vault.ymlConfiguration) + - 4.1. [Common Configuration](#CommonConfiguration) + - 4.2. [Initialization Environment Configuration](#InitializationEnvironmentConfiguration) + - 4.3. [Automation Hub Specific Configuration](#AutomationHubSpecificConfiguration) + - 4.4. [AWS-Specific Configuration](#AWS-SpecificConfiguration) + - 4.5. [ImageBuilder-Specific Configuration](#ImageBuilder-SpecificConfiguration) +- 1. [What the Framework Does, Step-by-Step](#WhattheFrameworkDoesStep-by-Step) + - 5.1. [Pre-GitOps Steps](#Pre-GitOpsSteps) + - 5.1.1. [Pre-init (mandatory)](#Pre-init) + - 5.1.2. [Environment Initialization (optional; enabled by default)](#EnvironmentInitialization) + - 5.1.3. [Containerized Install (`make install` default)](#ContainerizedInstall) + - 5.1.4. [OpenShift Targets](#OpenShiftTargets) + - 5.2. [GitOps Step](#GitOpsStep) +- 1. [Acknowledgements](#Acknowledgements) + This repository is part of Red Hat's [Validated Patterns](https://validatedpatterns.io) effort, which in general @@ -40,17 +43,30 @@ Platform, and as such to provide useful facilities for developing Patterns (comm The thinking behind this effort is documented in the [Ansible Pattern Theory](https://github.com/mhjacks/ansible-pattern-theory) repository. -## 1. How to Use It +## 1. Prerequisites + +- **Podman** (version 4.3.0 or later): All commands are run inside a utility container via `pattern.sh`. +- **An `~/agof_vault.yml` file**: Contains credentials, configuration variables, and secrets for the installation. See the [agof_vault.yml Configuration](#agof_vault.ymlConfiguration) section for details. +- **A Red Hat subscription**: Needed for RHEL entitlement and access to AAP content. +- **An [AAP manifest file](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/installing_on_openshift_container_platform/assembly-gateway-licensing-operator-copy#assembly-aap-obtain-manifest-files)**: Required to entitle the AAP Controller (see `manifest_content` in the configuration section). +- **An Automation Hub token**: For downloading certified and validated Ansible content from [console.redhat.com](https://console.redhat.com/ansible/automation-hub/token). +- **AWS credentials** (for the Default Install only): An AWS account with permissions to create VPCs, subnets, security groups, and EC2 instances. + +### About `pattern.sh` + +`pattern.sh` is the main entry point for running framework commands. It is a wrapper script that launches a utility container (via podman) with your home directory mounted, ensuring a consistent and reproducible execution environment. All `make` targets are run through it, e.g. `./pattern.sh make install`. -The default installation will provide an AAP 2.5 installation deployed via the Containerized Installer, with services deployed this way: +## 2. How to Use It + +The default installation will provide an AAP 2.5 installation deployed via the Containerized Installer, with the following services available on the AAP node (where `aapnode.fqdn` is the fully qualified domain name of your AAP host): | URL Pattern | Service | |-------------|---------| -| https://aapnode.fqdn3/ | Controller API | +| | Controller API | -Automation Hub and EDA are enabled by default, but they can be turned off if desired. +Automation Hub and EDA are enabled by default, but they can be turned off if desired (see the `automation_hub` and `eda` variables). -By default, the framework will apply license content specified by the `manifest_content` variable, but will not further configure Controller or Automation Hub beyond the defaults. +By default, the framework will apply license content specified by the `manifest_content` variable (see [obtaining a manifest file](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/installing_on_openshift_container_platform/assembly-gateway-licensing-operator-copy#assembly-aap-obtain-manifest-files)), but will not further configure Controller or Automation Hub beyond the defaults. From there, a minimal example pattern is available to download and run [here](https://github.com/validatedpatterns-demos/agof_minimal_config.git). To use this example, set the following variables in your `agof_vault.yml`. `agof_statedir` is where the config repo will be checked out by the process. Any repo that can be used with the controller_configuration collection can be used as the `agof_iac_repo`. @@ -60,7 +76,7 @@ agof_statedir: "{{ '~/agof' | expanduser }}" agof_iac_repo: "https://github.com/validatedpatterns-demos/agof_minimal_config.git" ``` -### 1.1. Installation +### 2.1. Installation ```shell ./pattern.sh make install @@ -68,7 +84,7 @@ agof_iac_repo: "https://github.com/validatedpatterns-demos/agof_minimal_config.g This builds the default pattern configuration on AWS, which (by default) includes a containerized install of AAP 2.5 on a single AWS VM. Various add-ons can be included by adding variables to the `~/agof_vault.yml` file as described below - these options will all be honored as the pattern installs itself. -### 1.2. Uninstallation +### 2.2. Uninstallation ```shell ./pattern.sh make aws_uninstall @@ -76,23 +92,19 @@ This builds the default pattern configuration on AWS, which (by default) include This destroys all of the AWS infrastructure built for the pattern - starting with the VPC it creates for the pattern and all of the resources attached to it. -## 2. Entry Points - -This is a framework for building Validated Patterns that use Ansible Automation Platform (AAP) as their underlying GitOps engine. To that end, the framework has these deployment models (in increasing level of complexity): - -## 3. Using the Containerized Installer vs. The traditional one +## 3. Installation Modes -In AAP 2.5, the containerized install feature has reached General Availability and is the preferred way to install AAP on non-OpenShift environments. +This is a framework for building Validated Patterns that use Ansible Automation Platform (AAP) as their underlying GitOps engine. The framework supports several installation modes (listed below in increasing level of complexity). In AAP 2.5, the containerized install feature has reached General Availability and is the preferred way to install AAP on non-OpenShift environments. -### 3.1. "API" Install (aka "Bare") +### 3.1. "API" Install (aka "Bare") ```shell ./pattern.sh make api_install ``` -In this model, you provide an (already provisioned) AAP endpoint. It does not need to be entitled, it just needs to be running the AAP Controller. You supply the manifest contents, endpoint hostname, admin username (defaults to "admin"), and admin password, and then the installation hands off to a `agof_controller_config_dir` you define. This is provided for users who have their own AAP installations on bare metal or on-prem or do not want to run on AWS. It is also useful in situations where the AAP deployment topology is more complex than what we provide in the pattern provisioner. +In this model, you provide an (already provisioned) AAP endpoint. It does not need to be entitled, it just needs to be running the AAP Controller. You supply the [manifest](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/installing_on_openshift_container_platform/assembly-gateway-licensing-operator-copy#assembly-aap-obtain-manifest-files) contents, endpoint hostname, admin username (defaults to "admin"), and admin password, and then the installation hands off to a `agof_controller_config_dir` you define. This is provided for users who have their own AAP installations on bare metal or on-prem or do not want to run on AWS. It is also useful in situations where the AAP deployment topology is more complex than what we provide in the pattern provisioner. -### 3.2. "From OS" Install +### 3.2. "From OS" Install ```shell ./pattern.sh make from_os_install INVENTORY=(your_inventory_file) @@ -103,12 +115,12 @@ in the aap_controllers group. (Many other topologies are possible with the AAP i The reason for making this a separate option is to make it easy for those who are not used to installing AAP to get up and running with it given a couple of VMs (or baremetal instances). Requirements for this mode are as follows: -* Must be running a version of RHEL that AAP supports -* Must be properly entitled with a RHEL subscription +- Must be running a version of RHEL that AAP supports +- Must be properly entitled with a RHEL subscription It is not possible to test all possible scenarios in this mode, and we do not try. -Note that INVENTORY defaults to '~/inventory_agof' if you do not specify one. +Note that INVENTORY defaults to `~/inventory_agof` if you do not specify one. Your inventory *must* define an `aap_controllers` group (which will be configured as the AAP node) and an `automation_hub` group which will be configured as the automation hub, if you want one. You must also specify `username` if you want it to be something besides the default 'ec2-user' (which it does not create or otherwise manage). Similarly, you should set `controller_hostname` (including the 'https://' schema) because that will default to something AWS-specific otherwise. As with all Ansible inventory files, you can set other variables here and the plays will use them. @@ -138,7 +150,7 @@ username=myuser aap_hostname=192.168.5.207 ``` -### 3.3. Default Install +### 3.3. Default Install ```shell ./pattern.sh make install @@ -146,7 +158,7 @@ aap_hostname=192.168.5.207 In this model, you provide AWS credentials in addition to the other components needed in the "bare" install. The framework will build an AWS image using Red Hat's ImageBuilder, deploy that image onto a new AWS VPC and subnet, and deploy AAP on that image using the command line installer. It will then hand over the configuration of the AAP installation to the specified `agof_controller_config_dir`. -### 3.4. Convenience Features Install (defined by options in the "default" install) +### 3.4. Convenience Features Install (defined by options in the "default" install) ```shell ./pattern.sh make install @@ -156,94 +168,98 @@ This model builds on the Default installation by adding the options for building The variables to include builds for the extra components are all Ansible booleans that can be included in your configuration: -`automation_hub` -`eda` +- `automation_hub` - Build and enable a Private Automation Hub instance +- `eda` - Build and enable an Event Driven Automation controller -## 4. agof_vault.yml Configuration +Additional VM targets (such as IdM and Satellite) can be defined using the `ec2_instances_xtra` variable in the AWS-Specific Configuration section. -### 4.1. Common Configuration +## 4. agof_vault.yml Configuration -| Name | Description | Required | Default | Notes | +### 4.1. Common Configuration + +| Name | Description | Required | Default | Notes | | ------------------------- | ------------------------------------ | -------- | -------- | ------ | -| admin_user | Admin User (for AAP and/or Hub) | false | 'admin' | | -| admin_password | Admin Password (for AAP and/or Hub) | true | | | -| redhat_username | Red Hat Subscriber Username | true | | | -| redhat_password | Red Hat Subscriber Password | true | | | -| redhat_registry_username_vault | Red Hat Subscriber Username | true | | | -| redhat_registry_password_vault | Red Hat Subscriber Password | true | | | -| manifest_content | Base64 encoded Manifest to Entitle | true | | Can be loaded directly from a file using a construct like this: `"{{ lookup('file', '~/Downloads/manifest.zip') | b64encode }}"` | -| automation_hub_certified_url | URL for Certified Content | false | | This refers to the automation hub section on [https://console.redhat.com](https://console.redhat.com). It is the endpoint that is used to download Validated Content in addition to any public Galaxy content needed | -| automation_hub_validated_url | URL for Validated Content | false | | This refers to the automation hub section on [https://console.redhat.com](https://console.redhat.com). It is the endpoint that is used to download Certified Content in addition to any public Galaxy content needed | -| automation_hub_token_vault| Subscriber-specific token for Content | true | | -| automation_hub | Flag to build and enable Automation Hub | false | false | | Building a Private Automation Hub is necessary if your pattern builds an Execution Environment that is not hosted on a public container registry. | -| eda | Flag to build and enable Event Driven Automation controller | false | true | | | -| agof_controller_config_dir | Directory to pass to controller_configuration | false | | This directory is the key one to load all other AAP Controller configuration. The framework will populate it by checking out the `agof_iac_repo` version `agof_iac_repo_version` (default: `main`) | -| controller_launch_jobs | List of jobs to run after controller_configuration has run | false | | Use this to start a job (or jobs) that do not have aggressive schedules, and that are ready to run as soon as the controller is configured. The fewer jobs listed here the better. | - -### 4.2. Initialization Environment Configuration - -| Name | Description | Required | Default | Notes | +| admin_user | Admin User (for AAP and/or Hub) | false | 'admin' | | +| admin_password | Admin Password (for AAP and/or Hub) | true | | | +| redhat_username | Red Hat Subscriber Username (for RHEL entitlement) | true | | | +| redhat_password | Red Hat Subscriber Password (for RHEL entitlement) | true | | | +| redhat_registry_username_vault | Red Hat Registry Username (for registry.redhat.io container images) | true | | | +| redhat_registry_password_vault | Red Hat Registry Password (for registry.redhat.io container images) | true | | | +| manifest_content | Base64 encoded [Manifest](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/installing_on_openshift_container_platform/assembly-gateway-licensing-operator-copy#assembly-aap-obtain-manifest-files) to Entitle | true | | Can be loaded directly from a file using a construct like this: `"{{ lookup('file', '~/Downloads/manifest.zip') | b64encode }}"` | +| automation_hub_certified_url | URL for Certified Content | false | | This refers to the automation hub section on [https://console.redhat.com](https://console.redhat.com). It is the endpoint that is used to download Certified Content in addition to any public Galaxy content needed | +| automation_hub_validated_url | URL for Validated Content | false | | This refers to the automation hub section on [https://console.redhat.com](https://console.redhat.com). It is the endpoint that is used to download Validated Content in addition to any public Galaxy content needed | +| automation_hub_token_vault| Subscriber-specific token for Content | true | | +| automation_hub | Flag to build and enable Automation Hub | false | false | | Building a Private Automation Hub is necessary if your pattern builds an Execution Environment that is not hosted on a public container registry. | +| eda | Flag to build and enable Event Driven Automation controller | false | true | | | +| agof_controller_config_dir | Directory to pass to controller_configuration | false | | This directory is the key one to load all other AAP Controller configuration. The framework will populate it by checking out the `agof_iac_repo` version `agof_iac_repo_version` (default: `main`) | +| controller_launch_jobs | List of jobs to run after controller_configuration has run | false | | Use this to start a job (or jobs) that do not have aggressive schedules, and that are ready to run as soon as the controller is configured. The fewer jobs listed here the better. | + +### 4.2. Initialization Environment Configuration + +| Name | Description | Required | Default | Notes | | ------------------------- | ------------------------------------ | -------- | -------- | ------------------ | -| init_env_collection_install | Whether to install collections required by the framework | false | true | | +| init_env_collection_install | Whether to install collections required by the framework | false | true | | | init_env_collection_install_force | Whether to use the `force` argument when installing collections | false | false | Forces the installation of declared dependencies if true | | special_collection_installs | "Bundled" collection installations (references files in repodir) | false | `[]` | A mechanism to allow the installation of collections bundled into the pattern, if the ones published in galaxy and/or Automation Hub are not sufficient | -| offline_token | Red Hat Offline Token | false | | Used to build the imagebuilder image | +| offline_token | Red Hat Offline Token | false | | Used to build the imagebuilder image | -### 4.3. Automation Hub Specific Configuration +### 4.3. Automation Hub Specific Configuration -| Name | Description | Required | Default | Notes | +| Name | Description | Required | Default | Notes | | ------------------------- | ------------------------------------ | -------- | ------------------ | ------ | -| aap_admin_username | Admin User (for AAP) | false | '{{ admin_user }}' | | -| aap_admin_password | Admin Password (for AAP) | true | '{{ admin_password }} ' | | -| private_hub_username | Admin User (for Automation Hub) | true | '{{ admin_user }}' | | -| private_hub_password | Admin Password (for Automation Hub) |true | '{{ admin_password }} ' | | -| custom_execution_environments | Array of Execution Environments to build on Hub | true | `[]` | The execution environments will be built on the hub node, and then pushed into the hub registry from there. | +| aap_admin_username | Admin User (for AAP) | false | '{{ admin_user }}' | | +| aap_admin_password | Admin Password (for AAP) | true | '{{ admin_password }} ' | | +| private_hub_username | Admin User (for Automation Hub) | true | '{{ admin_user }}' | | +| private_hub_password | Admin Password (for Automation Hub) |true | '{{ admin_password }} ' | | +| custom_execution_environments | Array of Execution Environments to build on Hub | true | `[]` | The execution environments will be built on the hub node, and then pushed into the hub registry from there. | -### 4.4. AWS-Specific Configuration +### 4.4. AWS-Specific Configuration -| Name | Description | Required | Default | Notes | +| Name | Description | Required | Default | Notes | | ------------------------- | ------------------------------------ | -------- | ------------------ | ------ | -| aws_account_nbr_vault | AWS Account Number | false | | The AWS Account Number is used by ImageBuilder to share the resulting image to as an AMI | -| aws_access_key_vault | AWS Access Key String | false | | The AWS Access Key - can be included if other pattern elements cannot read AWS credentials directly for subsequent pattern use | -| aws_secret_key_vault | AWS Secret Key String | false | | The AWS Secret Key - like the access key, can be added if other pattern elements need it | -| ec2_region | EC2 region to use for builds | false | | us-east-1 is a reasonable value to use because this is where imagebuilder puts images by default | -| ec2_name_prefix | Text to add for EC2 | false | | This is a name to disambiguate your pattern from anything else that might be running in your AWS account. A VPC, subnet, and security group is built from this, and the prefix is added to the `pattern_dns_zone` by default. Additionally, the SSH private key is stored locally in `~/{{ ec2_name_prefix }}`. | -| pattern_dns_zone | Zone to use for route53 updates | false | | Definitely set this if doing DNS updates | -| ec2_instances_xtra | Dictionary of additional ec2_instances to build | false | | Build additional VMs as part of the pattern | +| aws_account_nbr_vault | AWS Account Number | false | | The AWS Account Number is used by ImageBuilder to share the resulting image to as an AMI | +| aws_access_key_vault | AWS Access Key String | false | | The AWS Access Key - can be included if other pattern elements cannot read AWS credentials directly for subsequent pattern use | +| aws_secret_key_vault | AWS Secret Key String | false | | The AWS Secret Key - like the access key, can be added if other pattern elements need it | +| ec2_region | EC2 region to use for builds | false | | us-east-1 is a reasonable value to use because this is where imagebuilder puts images by default | +| ec2_name_prefix | Text to add for EC2 | false | | This is a name to disambiguate your pattern from anything else that might be running in your AWS account. A VPC, subnet, and security group is built from this, and the prefix is added to the `pattern_dns_zone` by default. Additionally, the SSH private key is stored locally in `~/{{ ec2_name_prefix }}`. | +| pattern_dns_zone | Zone to use for route53 updates | false | | Definitely set this if doing DNS updates | +| ec2_instances_xtra | Dictionary of additional ec2_instances to build | false | | Build additional VMs as part of the pattern | -### 4.5. ImageBuilder-Specific Configuration +### 4.5. ImageBuilder-Specific Configuration *Note:* If you are providing an AMI via the `imagebuilder_ami` variable as opposed to building one from console.redhat.com for the pattern, the pattern still assumes that the RHEL instance will be entitled and will be running a suitable version of RHEL. -| Name | Description | Required | Default | Notes | +| Name | Description | Required | Default | Notes | | ------------------------- | ------------------------------------ | -------- | ------------------ | ------- | -| org_number_vault | Red Hat Subscriber Organization Number | true | | This is the organization number associated with the RHEL instances you need to entitle | -| activation_key_vault | Activation Key Name to embed in image | true | | This is an activation key for the Red Hat CDN. It is expected to be able to enable both the base RHEL repos and the AAP repos. | -| skip_imagebuilder_build | Flag to skip imagebuilder build (also set `imagebuilder_ami` if true) | false | false | | -| imagebuilder_ami | AMI to use for VM creation in AWS | false | | It is very possible to re-use another imagebuilder build from a previous installation of the pattern framework, and saves ~15 minutes on a new pattern install to re-use such an image. | -| ami_source_region | Source Region to copy AMI from if not present in target region | false | us-east-1 | Imagebuilder puts its images in us-east-1 by default, but the framework can copy an image built there to another region if you specify one here. If you specify a non-imagebuilder ami and it "starts out" in a different region, you can specify that here. | +| org_number_vault | Red Hat Subscriber Organization Number | true | | This is the organization number associated with the RHEL instances you need to entitle | +| activation_key_vault | Activation Key Name to embed in image | true | | This is an activation key for the Red Hat CDN. It is expected to be able to enable both the base RHEL repos and the AAP repos. | +| skip_imagebuilder_build | Flag to skip imagebuilder build (also set `imagebuilder_ami` if true) | false | false | | +| imagebuilder_ami | AMI to use for VM creation in AWS | false | | It is very possible to re-use another imagebuilder build from a previous installation of the pattern framework, and saves ~15 minutes on a new pattern install to re-use such an image. | +| ami_source_region | Source Region to copy AMI from if not present in target region | false | us-east-1 | Imagebuilder puts its images in us-east-1 by default, but the framework can copy an image built there to another region if you specify one here. If you specify a non-imagebuilder ami and it "starts out" in a different region, you can specify that here. | + +## 5. What the Framework Does, Step-by-Step -## 5. What the Framework Does, Step-by-Step +> **Note:** The following sections describe the internal workings of the framework. They are not required reading for basic installation and usage -- see the [Installation Modes](#InstallationModes) and [Configuration](#agof_vault.ymlConfiguration) sections above for that. -### 5.1. Pre-GitOps Steps +### 5.1. Pre-GitOps Steps -#### 5.1.1. [Pre-init](init_env/pre_init_env.yml) (mandatory) +#### 5.1.1. Pre-init (mandatory) Pre-initialization, for our purposes, refers to things that have to be installed on the installation workstation/provisioner node to set up the Ansible environment to deploy the rest of the pattern. ##### Build ansible.cfg -Because ansible.cfg needs to be configured with the automation hub endpooint, we generate it from a template. The ansible.cfg includes endpoints for both public and Automation Hub galaxy servers and a vault password path (for `ansible-vault`). The template used is [here](init_env/templates/ansible.cfg.j2). The automation hub token is read from the vault and injected into the environment for the collection installation phase. +Because ansible.cfg needs to be configured with the automation hub endpoint, we generate it from a template. The ansible.cfg includes endpoints for both public and Automation Hub galaxy servers and a vault password path (for `ansible-vault`). The template used is [here](pre_init/templates/ansible.cfg.j2). The automation hub token is read from the vault and injected into the environment for the collection installation phase. ##### Collection dependency install The next thing the pre-init play does is install dependency collections based on what's contained in [requirements.yml](requirements.yml). If there are any "special" collections contained in the root of the framework they can also be installed at this time. When the framework was under development this was necessary with redhat.satellite but the necessary changes have been upstreamed as of 3.11; 3.12 has been released since then, so this mechanism is no longer needed but is left in as it might be necessary in the future. -#### 5.1.2. [Environment Initialization](init_env/main.yml) (optional; enabled by default; `make install` entry point) +#### 5.1.2. [Environment Initialization](init_env/main.yml) (optional; enabled by default; `make install` entry point) Environment initialization includes the steps necessary to build the environment (VMs) to install AAP and related tooling; currently the framework can do this on AWS. This step is optional if you wish to provide either an AAP controller API endpoint OR else bring your own inventory/VMs to install AAP Controller and (optionally) Automation Hub on. -##### [image build (optional)](buildimage/main.yml) (optional) +##### [Image build (optional)](init_env/buildimage/main.yml) (optional) This play builds an image using the Red Hat Console's imagebuilder service; the end result of this process is an image that will serve as an AMI in AWS. (ImageBuilder can build other types of images as well.) The key aspects of this image are that they include the cloud-init package (which helps with certain aspects of initialization), but more importantly, they include the organization number and activation key so that images that are instantiated with this AMI are automatically registered and enabled to install content via the Red Hat CDN. @@ -257,59 +273,59 @@ The two key roles that are invoked here are [manage_ec2_infra](init_env/aws/role These roles also include code for making hostnames durable across reboots, as well as maintaining `/etc/hosts` on all AWS nodes in the bootstrap set that include all of the other servers in the bootstrap set. -##### [Update Route53 DNS (if needed))](init_env/aws/fix_aws_dns.yml) +##### [Update Route53 DNS (if needed)](init_env/aws/fix_aws_dns.yml) The standard public IPs that are offered by AWS (which are used by this framework) are not permanently associated with the VMs. When the VMs cold start, in particular, we can expect IP change events. The VMs themselves are not directly aware of their external IPs. In order to handle this situation, this play can be run from the provisioner node/workstation to update the route53 DNS mappings based on the AWS API. -##### [Teardown AWS Environment)](init_env/aws/teardown.yml) (`make aws_uninstall`) +##### [Teardown AWS Environment](init_env/aws/teardown.yml) (`make aws_uninstall`) The teardown play will terminate all VMs associated with a VPC and subnet, and remove the DNS entries managed by the "bootstrap set" (which are just the VMs the framework has been told it has to build). -#### 5.1.3. [Containerized Install](containerized_install/main.yml) (`make install` default) +#### 5.1.3. [Containerized Install](containerized_install/main.yml) (`make install` default) -| Name | Description | Required | Default | Notes | +| Name | Description | Required | Default | Notes | | ------------------------- | ------------------------------------ | -------- | ------------------ | ------- | -| containerized_installer_user | Unprivileged user to create to run AAP | true | `aap` | | -| containerized_installer_user_home | Directory to install containerized AAP into | true | `/home/{{ containerized_installer_user }}` | | -| containerized_installer_version | Minor version of AAP to install | false | "2.5" | | -| automation_hub | Boolean to indicate whether to install automation_hub | true | true | | -| postgresql_admin_username | Name of postgres admin for services | true | `postgres` | | -| postgresql_admin_password | Password for the postgres user for services | true | `{{ db_password }}` | | -| ee_extra_images | Specifications for extra execution environments to load | false | `[]` | | -| de_extra_images | Specifications for extra decision environments to load (for EDA) | false | `[]` | | -| controller_postinstall | Whether or not to use controller_postinstall feature | false | `false` | | -| controller_postinstall_repo_url | Repository URL for additional controller configuration | false | | | -| controller_postinstall_repo_ref | Tag, branch or SHA in the repo to use for configuration | false | `main` | | -| controller_postinstall_dir | Directory to use to load additional controller config | false | | Prefer using the `controller_postinstall_repo_url` as it is more flexible | -| hub_admin_password | Admin user password for automation_hub service | false | '{{ admin_password }}' | | -| hub_pg_password | Postgres password for automation_hub service | false | '{{ db_password }}' | | -| hub_postinstall | Whether to use the `hub_postinstall` feature | false | false | | -| hub_postinstall_dir | Directory to use for hub_postinstall if enabled | false | | Prefer hub_postinstall_repo options as they are more flexible | -| hub_postinstall_repo_url | Repository to use for hub_postinstall if enabled | false | | | -| hub_postinstall_repo_ref | Branch, tag, or sha to use in repo for hub postinstall | false | `main` | | -| hub_workers | How many worker containers to run | false | `2` | | -| hub_collection_signing | Whether to sign collections automatically | false | `false` | | -| hub_collection_signing_key | GPG key to sign collections with, if desired | false | | | -| hub_container_signing | Whether to sign containers automatically | false | `false` | | -| hub_container_signing_key | GPG key to sign containers (EE's and DE's) with, if desired | false | | | -| eda_admin_password | EDA Service admin password | false | `{{ admin_password }}` | | -| eda_pg_password | EDA Service postgres password | false | `{{ db_password }}` | | -| eda_workers | Number of EDA workers | false | `2` | | -| eda_activation_workers | Number of EDA activation workers | false | `2` | | +| containerized_installer_user | Unprivileged user to create to run AAP | true | `aap` | | +| containerized_installer_user_home | Directory to install containerized AAP into | true | `/home/{{ containerized_installer_user }}` | | +| containerized_installer_version | Minor version of AAP to install | false | "2.5" | | +| automation_hub | Boolean to indicate whether to install automation_hub | true | true | | +| postgresql_admin_username | Name of postgres admin for services | true | `postgres` | | +| postgresql_admin_password | Password for the postgres user for services | true | `{{ db_password }}` | | +| ee_extra_images | Specifications for extra execution environments to load | false | `[]` | | +| de_extra_images | Specifications for extra decision environments to load (for EDA) | false | `[]` | | +| controller_postinstall | Whether or not to use controller_postinstall feature | false | `false` | | +| controller_postinstall_repo_url | Repository URL for additional controller configuration | false | | | +| controller_postinstall_repo_ref | Tag, branch or SHA in the repo to use for configuration | false | `main` | | +| controller_postinstall_dir | Directory to use to load additional controller config | false | | Prefer using the `controller_postinstall_repo_url` as it is more flexible | +| hub_admin_password | Admin user password for automation_hub service | false | '{{ admin_password }}' | | +| hub_pg_password | Postgres password for automation_hub service | false | '{{ db_password }}' | | +| hub_postinstall | Whether to use the `hub_postinstall` feature | false | false | | +| hub_postinstall_dir | Directory to use for hub_postinstall if enabled | false | | Prefer hub_postinstall_repo options as they are more flexible | +| hub_postinstall_repo_url | Repository to use for hub_postinstall if enabled | false | | | +| hub_postinstall_repo_ref | Branch, tag, or sha to use in repo for hub postinstall | false | `main` | | +| hub_workers | How many worker containers to run | false | `2` | | +| hub_collection_signing | Whether to sign collections automatically | false | `false` | | +| hub_collection_signing_key | GPG key to sign collections with, if desired | false | | | +| hub_container_signing | Whether to sign containers automatically | false | `false` | | +| hub_container_signing_key | GPG key to sign containers (EE's and DE's) with, if desired | false | | | +| eda_admin_password | EDA Service admin password | false | `{{ admin_password }}` | | +| eda_pg_password | EDA Service postgres password | false | `{{ db_password }}` | | +| eda_workers | Number of EDA workers | false | `2` | | +| eda_activation_workers | Number of EDA activation workers | false | `2` | | First, we run the [Installer Prereqs](containerized_install/roles/installer_prereqs/) role. This sets up a user (default: `aap`) to run AAP as, sets up password-less sudo for that user, and installs the pattern user's `~/.ssh/id_rsa.pub` as an authorized_key for the user. The sudo rule simplifies the process of running the containerized installer, and by default is removed in the cleanup stage. This role also sets `linger` on the AAP user so that services will start at boot time under the AAP user. -Next, we run the [Containerized Installer](containerized_install/roles/installer/) role. This runs the containerized installer as the designated user. This user _cannot_ be root (because of how it uses and configures containerized services). This role downloads and executes the installer, and also places a manifest file (designated by the `manifest_content` variable) as `manifest.zip` to entitle the controller. It runs the containerized installer. +Next, we run the [Containerized Installer](containerized_install/roles/installer/) role. This runs the containerized installer as the designated user. This user *cannot* be root (because of how it uses and configures containerized services). This role downloads and executes the installer, and also places a [manifest file](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/installing_on_openshift_container_platform/assembly-gateway-licensing-operator-copy#assembly-aap-obtain-manifest-files) (designated by the `manifest_content` variable) as `manifest.zip` to entitle the controller. It runs the containerized installer. Finally, we run the [cleanup](containerized_install/roles/installer_cleanup/) role if it is enabled (which it is by default). This removed the sudo rule from the AAP user, and removes the manifest.zip file. The installation is now ready for you to use. ##### [AAP Configuration](configure_aap.yml) (mandatory for non-containerized install; `make api_install` entry point) -This play is really the heart and focus of this framework. The rest of the framework exists to facilitate running this play, and providing additional capabilities to the environment in which the play runs. The logic for the play is contained in the [configure_aap](hosts/roles/configure_aap/) role. The `make api_install` entry point uses just the variables related to controller installation as desribed [here](#api-install-aka-bare). Otherwise, it is called inline from the `make install` entry point. It is safe to run multiple times. +This play is really the heart and focus of this framework. The rest of the framework exists to facilitate running this play, and providing additional capabilities to the environment in which the play runs. The logic for the play is contained in the [configure_aap](agof_configure_aap/roles/configure_aap/) role. The `make api_install` entry point uses just the variables related to controller installation as desribed [here](#APIInstallakaBare). Otherwise, it is called inline from the `make install` entry point. It is safe to run multiple times. ###### Entitle AAP -The play uses the same technique and variables to entitle AAP as the role above does; but since we want to preserve the option to call it outside that role, it is duplicated. The key thing is to populate `manifest_contents` with a suitable manifest file. +The play uses the same technique and variables to entitle AAP as the role above does; but since we want to preserve the option to call it outside that role, it is duplicated. The key thing is to populate `manifest_contents` with a suitable [manifest file](https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/installing_on_openshift_container_platform/assembly-gateway-licensing-operator-copy#assembly-aap-obtain-manifest-files). ###### Configure AAP @@ -318,7 +334,7 @@ Using the credentials you supply, the play will now proceed to invoke the `aap_c If you need any jobs to be run immediately, then can be specified using the `launch_job` type as part of the AAP configuration repo. -#### 5.1.4. OpenShift Targets +#### 5.1.4. OpenShift Targets Designed to run under OpenShift and configure an OpenShift-hosted AAP instance, AGOF has some special handling for these targets. It is meant to be used by the Validated Patterns aap-config chart, which is meant to run agof_vault.yml @@ -327,27 +343,27 @@ Since the OpenShift Validated Patterns experience uses HashiCorp Vault as a secr Additionally, AGOF expects an agof_vault.yml file for any other secret material, which will be included in OpenShift as well. This means that you do not have to use the Vault integration if you would rather not. -Because the AGOF runner needs predicatability for the existence of the manifest file and the IAC repo and revision, it overrides these specific elements from vault with its own override file, which is created as `~/agof_overrides.yml`. This file is included as the last extra_vars file on the playbook command line. It specifically sets these variables: +Because the AGOF runner needs predictability for the existence of the manifest file and the IAC repo and revision, it overrides these specific elements from vault with its own override file, which is created as `~/agof_overrides.yml`. This file is included as the last extra_vars file on the playbook command line. It specifically sets these variables: -* `aap_entitled`: Based on examing the AAP endpoint, whether the instance has been entitled or not -* `admin_user`: Hardcoded to `admin` currently. -* `admin_password`: Has the value of the password randomly generated by the AAP Operator installation -* `aap_hostname`: The endpoint of the AAP instance, as discovered by looking for its route in the ansible-automation-platform namespace -* `agof_iac_repo`: Set by retrieving it from the helm values, so that it overries what may be in your local `agof_vault.yml` file. -* `agof_iac_repo_version`: Set by retrieving it from the Helm chart, as above. -* `controller_license_src_file`: Set by creating a temporary file from the manifest file secret -* `secrets`: Special data structure that contains other elements discovered from OpenShift. -* `helm_values`: All of the helm values available to the application. +- `aap_entitled`: Based on examining the AAP endpoint, whether the instance has been entitled or not +- `admin_user`: Hardcoded to `admin` currently. +- `admin_password`: Has the value of the password randomly generated by the AAP Operator installation +- `aap_hostname`: The endpoint of the AAP instance, as discovered by looking for its route in the ansible-automation-platform namespace +- `agof_iac_repo`: Set by retrieving it from the helm values, so that it overrides what may be in your local `agof_vault.yml` file. +- `agof_iac_repo_version`: Set by retrieving it from the Helm chart, as above. +- `controller_license_src_file`: Set by creating a temporary file from the manifest file secret +- `secrets`: Special data structure that contains other elements discovered from OpenShift. +- `helm_values`: All of the helm values available to the application. Additionally, the `agof_vault.yml` file that is passed to Vault will be used as the agof_vault.yml file inside the configuration container, so any variables set here will be usable by the framework; but any of the values listed above will be overridden by the overrides file. The goal is to provide as similar an experience as possible between the different ways of running AGOF. Meanwhile, the helm values that have been passed into the aap-config application will be available in the `helm_values` variable. -### 5.2. GitOps Step +### 5.2. GitOps Step The framework is only truly in GitOps mode once the configuration has been fully applied to the AAP controller and the AAP controller has taken responsibility for managing the environment. Prior to that point, there are many opportunities (by design) to inject non-declarative elements into the environment. Beyond that point, changes should be made to the environment or the workflows that configure it by pushing git commits to the repositories the pattern uses. -## 6. Acknowledgements +## 6. Acknowledgements This repository represents an interpretation of GitOps principles, as developed in the Hybrid Cloud Patterns GitOps framework for Kubernetes, and an adaptation and fusion of two previous ongoing efforts at Red Hat: [Ansible-Workshops](https://github.com/ansible/workshops) and [LabBuilder2/RHISbuilder](https://github.com/parmstro/labbuilder2). diff --git a/agof_vault_template.yml b/agof_vault_template.yml index 2858369..5ed357f 100644 --- a/agof_vault_template.yml +++ b/agof_vault_template.yml @@ -17,7 +17,7 @@ redhat_password: 'Red Hat Subscription password, used to login to registry.redha admin_password: 'An admin password for AAP Controller and Automation Hub' -# https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.4/html-single/red_hat_ansible_automation_platform_operations_guide/index#proc-create-subscription-allocation_obtain-manifest +# https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/installing_on_openshift_container_platform/assembly-gateway-licensing-operator-copy manifest_content: "Content for a manifest file to entitle AAP Controller. See below for an example of how to point to a local file" #manifest_content: "{{ lookup('file', '~/Downloads/manifest_AVP_20230510T202608Z.zip') | b64encode }}" diff --git a/pre_init/jwt_check.yml b/pre_init/jwt_check.yml index 4c9c6e3..bd62891 100644 --- a/pre_init/jwt_check.yml +++ b/pre_init/jwt_check.yml @@ -69,5 +69,6 @@ msg: > "The {{ local_token_name }} token was generated more than 30 days ago {{ '%Y-%m-%d %H:%M' | strftime(jwt_iat) }}, " "you should renew your token. We're continuing, but chances are there might be issues with the token." + "You can renew your offline RHSM token at: https://access.redhat.com/management/api" when: (iat_after_duration | int < ansible_date_time['epoch'] | int) ignore_errors: true