1 Configuring the buildimage variables
This page provides additional documentation about the buildimage components, the variables used and where to get the info for them.
The buildimage folder contains the ansible code to call the imagebuilder service on console.redhat.com to build a RHEL image. That image gets used for the first two systems in our Red Hat Infrastructure Standard Adoption Model - the primary IdM server and the Satellite server.
The code performs the following tasks are completed:
- ensure that we can connect to and test the imagebuilder API
- ensure that the desired image definition is templated
- initiate an image compose
- ensure the the finished compose is downloaded to our build orchestration machine
- ensure the image is uploaded to the target environment (currently vcenter or azure)
- ensure a vm for the idm primary server is created and running
- ensure a vm for satellite is created and running
Once these tasks are complete the next phase of our build takes over - initializing the Identity Management environment.
Figure 1: This is a high level view of the flow for buildimage.
In the vars directory there are a series of yml files that manage the settings to configure the process. The files follow a pattern that is used throughout the project.
-
element_vars.yml - contains the variables required to configure the component.
-
element_vault.yml - contains the variablename_vault values for variables values that need to be kept private.
e.g. The task to build the image uses the offline_token variable in code. It's definition in builder_vars.yml references offline_token_vault. offline_token_vault is defined in a file called builder_vault.yml and the file is encrypted using ansible vault. You are required to provide all *_vault.yml files. They are ignored in git.
The image and its file system layout are created using the template.request-base-image.json.j2 file in the templates directory. Our default is minimal image with a file system layout that can meet compliance standards and the needs for resizing elements for the satellite deployment. Both IdM and Satellite start from minimal installs and the deployment pulls in all the required dependencies. Typically, no other code runs on these systems.
You need a valid offline token from console.redhat.com to generate access tokens for the API. See Getting Started with Red Hat APIs for an overview. Generate your offline token at API Management
The userdata and metadata files are used to generate our cloud_init configuration to work with the RHEL image. Unfortunately there are some bugs in vmware that prevent some of the static configuration from sticking when using cloud init. We work around this by stuffing the configuration into our runcmd. It only needs to work once. :-)
Once you have configured your builder, idm, sat and vmware variables, you can run main.yml on from you build orchestration machine and wait for 20 minutes (or less if you are running something more powerful than a gen5 NUC) to check things out. If you are confident, the site.yml file in the root labbuilder2 directory will invoke buildimage/main.yml as part of building the whole environment.
offline_token: a reference to the actual token that gets used to access the imagebuilder API
offline_token_vault: located in builder_vault.yml - the actual offline token.
encrypt builder_vault.yml using ansible vault.
auth_url: provided. the OID connect url for the console.redhat.com API servers
build_url: provided. the public url for the imagebuilder API
build_status_url: provided. the public url for the compose results from imagebuilder
azure_tenant_id: a reference to the actual value that gets used to login to azure
azure_tenant_id_vault: located in builder_vault.yml - the actual azure_tenant_id.
encrypt builder_vault.yml using ansible vault.
azure_subscription_id: a reference to the value that gets used to login to azure
azure_subscription_id_vault: located in builder_vault.yml - the actual azure_subscription_id.
encrypt builder_vault.yml using ansible vault.
azure_resource_group: the name of the resource group containing image storage.
This is used by image builder to load the composed image
directly to the azure cloud.
image_definition_file: the name of the output file for the templated imaged definition.
This get sent to imagebuilder.
imagebuilder_image_type: documented in the variable file.
The type of image you want imagebuilder to create.
builder_distribution: the RHEL distribution you want imagebuilder to create
builder_image_extension: the proper extension for the resulting image. see builder_vars.yml
Some platforms are finicky.
org_number: the organization number for your account on the Red Hat CDN
activation_key: the name of the activation key you have created in your
account to authorize your IdM server and Satellite
All volumes are created using LVM
Volume sizes here are for the default template which
supports a CIS Server Level 2 compliant configuration.
See buildimage/templates/ for the default template.
slash_size: the size in bytes of the root volume
home_size: the size in bytes of the volume for /home
var_size: the size in bytes of the volume for /var
tmp_size: the size in bytes of the volume for /tmp
var_tmp_size: the size in bytes of the volume for /var/tmp
var_log_size: the size in bytes of the volume for /var/log
var_log_audit_size: the size in bytes of the volume for /var/log/audit
azure_upload_request: defines the upload request payload for azure
vsphere_upload_request: defines the upload request payload for vmware vsphere
The metadata and userdata files for each system describe cloud-init configuration for each system that we will eventually use for vwmare when we upload the image. The actual values in these files are converted to base64 hashes and then injected with the image when uploaded to vmware. The metadata and userdata files are encrypted with ansible vault to protect the secrets in them. The base64 hashes are also stored in files protected by ansible vault. SAMPLE_ files are provided for you to create your own files. Use the gen_cloudinit_data.sh script to create the idm_vault.yml and sat_vault.yml files from your metadata and userdata files. Use ansible vault to encrypt your _vault.yml files. The script generates the following variables:
idm_cloud_init_metadata_vault: the base64 encoded metadata for the idm primary server
idm_cloud_init_userdata_vault: the base64 encoded userdata for the idm primary server
sat_cloud_init_metadata_vault: the base64 encoded metadata for the satellite server
sat_cloud_init_userdata_vault: the base64 encoded userdata for the satellite server
idm_vars.yml and sat_vars.yml will reference the respective variables _vault.yml files
This file contains the variables that define the virtual machine configuration for your target environment (only VMware today)
These values should be self explanatory.
This file contains the variables that define the virtual machine configuration for your target environment (only VMware today)
Additionally, this file describes the final sizes for target volumes on Satellite as the system has some considerable storage requirements.
These values should be self explanatory.
If you have buildimage configuration all sorted out, the next step is to jump over to the idm folder and set up your idm users, groups, sudo, hbac, and other configuration for the environment.