Installing Hybrid DNS Update - Adaptive Applications - BlueCat Gateway - 24.1

Hybrid DNS Update Administration Guide
ft:locale
en-US
Product name
BlueCat Gateway
Version
24.1
Before you begin, you must download the latest BlueCat Gateway image that contains Hybrid DNS Update.

Before you begin:

When you first install the Hybrid DNS Update Adaptive Application, BlueCat recommends performing the following:
  • Define a workspace:
    • A workspace is the logical location for you to place your workflows and associated data, including configurations, libraries, requirements, permissions, and customizations; a workspace can be a Docker volume (recommended) or a volume on your local machine. For more information, refer to the Workspace section in the BlueCat Gateway Administration Guide.
  • Define a logs directory:
    • A logs directory can be a Docker volume (recommended) or a volume on your local machine
Tip: BlueCat advises all customers to map Docker volumes for their respective workspace and logs directory to save data from the Hybrid DNS Update Adaptive Application. Volumes are completely managed by Docker and you do not need to set permissions manually when using Docker volumes. This is also the recommended practice for Docker containers. However, if you prefer to mount data and log volumes to your local machine, you must manually set rwx (read, write, execute) permissions to those directories before running the container. If you do not map data or log volumes to your local machine during installation, the Hybrid DNS Update Adaptive Application will write all the data to the container by default. If you then stop or restart the container, all this data will be lost.
To set permissions to external volumes, run the following command:
chmod -R o=rwx <mapped volume>
Note:
  • You can name the workspace and logs directory to anything.
  • The Hybrid DNS Update Adaptive Application saves configuration and workflow data to the workspace, and all execution and session logs to the mapped logs directory. If you do not map a workspace or a logs directory, all the configuration and logging data is written to anonymous volumes by default.
To install Hybrid DNS Update:
  1. From the host machine, run the following command:
    docker login quay.io
  2. At the prompt, enter your Quay user name and password obtained when generating the encrypted password.
  3. Download the Hybrid DNS Update Adaptive Application from Quay using the following command:
    docker pull quay.io/bluecat/hybrid_dns_update:24.1
  4. Start the custom Gateway image using the following command:
    docker run -d \
-p 80:8000 \
-p 443:44300 \
-v <path_to_workspace>:/bluecat_gateway/ \
-v <path_to_mapped_log_directory>:/logs/ \
-e BAM_IP=<your_bam_ip_address> \
-e VAULT_URL=<vault_url> \
-e VAULT_TOKEN=<vault_token_id> \
-e AWS_REGION=<aws_region_name> \
-e AZURE_KEY_VAULT=<azure_key_vault_name> \
--name <gateway_container_name> \
quay.io/bluecat/hybrid_dns_update:24.1
    Where:
    • <path_to_workspace> represents the directory where the Hybrid DNS Update configuration files will be stored.
    • <path_to_mapped_log_directory> represents the directory where the BlueCat Gateway logs are stored.
    • <volume-name> represents the name of the docker volume created for persistent storage.
    • <vault_url> represents the HashiCorp Vault URL.
    • <vault_token_id> represents the token to access the HashiCorp Vault URL.
    • <aws_region_name> represents the name of the AWS region.
    • <azure_key_vault_name> represents either the name of Azure key vault, such as MySecrets, or the full URL of the key vault, such as https://MySecrets.vault.azure.net.
      Note: If Hybrid DNS Update is running on an Azure Virtual Machine, you can assign vault access to the VM. For more information, refer to https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/howto-assign-access-portal.
    Note: Configuring Hybrid DNS Update to use Azure Key Vault when the Docker container is running on a local machine
    If you are using Hybrid DNS Update to use Azure Key Vault or another resource related to Azure, and the Docker container is running on a local machine, you must configure DefaultAzureCredential though docker environment variables. Configuring the AZURE_TENANT_ID and AZURE_CLIENT_ID are required for DefaultAzureCredential to check the environment configuration and look for one of the following additional environment variables to authenticate:
    • Setting environment variable AZURE_CLIENT_SECRET configures the DefaultAzureCredential to choose ClientSecretCredential.
    • Setting environment variable AZURE_CLIENT_CERTIFICATE_PATH configures the DefaultAzureCredential to choose ClientCertificateCredential if AZURE_CLIENT_SECRET is not set.
    • Setting environment variable AZURE_USERNAME configures the DefaultAzureCredential to choose UsernamePasswordCredential if AZURE_CLIENT_SECRET and AZURE_CLIENT_CERTIFICATE_PATH are not set.
    For example, you would the following environment variables in the docker run command when starting the container:
    ...
-e AZURE_TENANT_ID=<tenant_id> \
-e AZURE_CLIENT_ID=<client_id> \
-e AZURE_CLIENT_SECRET=<client_secret> \
...
    Note: Configuring Hybrid DNS Update to use Secret Manager when the Docker container is running on a local machine

    If you are using Hybrid DNS Update to use AWS Secret Manager or another resource related to AWS, and the Docker container is running on a local machine, you must configure the Secret Manger credentials though docker environment variables. Configuring the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are required to check the environment configuration.

    For example, you would configure the following environment variables in the docker run command when starting the container:
    ...
-e AWS_ACCESS_KEY_ID=<aws_access_key> \
-e AWS_SECRET_ACCESS_KEY=<aws_secret_key> \
...
    Note: Using Hybrid DNS Update with BlueCat Overlay for Microsoft
    If you are using Hybrid DNS Update with BlueCat Overlay for Microsoft, Hybrid DNS Update includes APIs that can also make updates to Microsoft DNS and Microsoft DHCP. By default, the DHCP APIs are not available using the standard docker run command. To enable the additional network and IP addresses APIs that are available in this configuration, specify the following additional environment variable in the docker run command:
    • SERVICE=ALL
    Note: If you are using RHEL with SELinux controls enabled, you must add a :Z option to the end of the path of any mapped volume. This modifies the SELinux label of the directory that is mounted to the container and should not be used with the system directories that are used with other applications, such as the /home directory.
Hybrid DNS Update contains a configuration file within /bluecat_gateway/workflows/Hybrid\ DNS\ Update/config/config.ini that is updated by the Hybrid DNS Update installation workflow. In managed environments where the Hybrid DNS Update container is deployed automatically and must be stateless, the following configuration parameters can be passed in as environment variables in the docker run command:
  • SERVICE_USERNAME—name of the BlueCat Gateway user that will be used to provide privilege elevation.
  • SERVICE_PASSWORD—encrypted password for the BlueCat Gateway user that will be used to provide privilege elevation.

When the configuration parameters are passed in as environment variables, the corresponding values in the configuration file are ignored. To update the configuration provided in the environment variables, you must delete and redeploy the Hybrid DNS Update container.

Configuring Hybrid DNS Update with persistent storage

Starting in Hybrid DNS Update v21.3.1, you can configure visibility jobs to use a persistent volume to ensure that in the instance of a container shutdown, the visibility jobs are not lost and can be restarted once the container is restarted.

To configure the Hybrid DNS Update image with a persistent volume:
  1. Create a docker volume using the following command:
    docker volume create <volume-name>
    Note: The persistent volume can only be used when starting a new container.
  2. Run a new container with the volume created using the following command:
    docker run -d \
-p 80:8000 \
-p 443:44300 \
-v <path_to_workspace>:/bluecat_gateway/ \
-v <path_to_mapped_log_directory>:/logs/ \
-v <volume-name>:/var/lib/postgresql/ \
-e BAM_IP=<your_bam_ip_address> \
-e VAULT_URL=<vault_url> \
-e VAULT_TOKEN=<vault_token_id> \
-e AWS_REGION=<aws_region_name> \
-e AZURE_KEY_VAULT=<azure_key_vault_name> \
--name <gateway_container_name> \
quay.io/bluecat/hybrid_dns_update:24.1
    Where:
    • <path_to_workspace> represents the directory where the Hybrid DNS Update configuration files will be stored.
    • <path_to_mapped_log_directory> represents the directory where the BlueCat Gateway logs are stored.
    • <volume-name> represents the name of the docker volume created for persistent storage.
    • <vault_url> represents the HashiCorp Vault URL.
    • <vault_token_id> represents the token to access the HashiCorp Vault URL.
    • <aws_region_name> represents the name of the AWS region.
    • <azure_key_vault_name> represents either the name of Azure key vault, such as MySecrets, or the full URL of the key vault, such as https://MySecrets.vault.azure.net.
      Note: If Hybrid DNS Update is running on an Azure Virtual Machine, you can assign vault access to the VM. For more information, refer to https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/howto-assign-access-portal.
    Note: Configuring Hybrid DNS Update to use Azure Key Vault when the Docker container is running on a local machine
    If you are using Hybrid DNS Update to use Azure Key Vault or another resource related to Azure, and the Docker container is running on a local machine, you must configure DefaultAzureCredential though docker environment variables. Configuring the AZURE_TENANT_ID and AZURE_CLIENT_ID are required for DefaultAzureCredential to check the environment configuration and look for one of the following additional environment variables to authenticate:
    • Setting environment variable AZURE_CLIENT_SECRET configures the DefaultAzureCredential to choose ClientSecretCredential.
    • Setting environment variable AZURE_CLIENT_CERTIFICATE_PATH configures the DefaultAzureCredential to choose ClientCertificateCredential if AZURE_CLIENT_SECRET is not set.
    • Setting environment variable AZURE_USERNAME configures the DefaultAzureCredential to choose UsernamePasswordCredential if AZURE_CLIENT_SECRET and AZURE_CLIENT_CERTIFICATE_PATH are not set.
    For example, you would configure the following environment variables in the docker run command when starting the container:
    ...
-e AZURE_TENANT_ID=<tenant_id> \
-e AZURE_CLIENT_ID=<client_id> \
-e AZURE_CLIENT_SECRET=<client_secret> \
...
    Note: Configuring Hybrid DNS Update to use Secret Manager when the Docker container is running on a local machine

    If you are using Hybrid DNS Update to use AWS Secret Manager or another resource related to AWS, and the Docker container is running on a local machine, you must configure the Secret Manger credentials though docker environment variables. Configuring the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are required to check the environment configuration.

    For example, you would configure the following environment variables in the docker run command when starting the container:
    ...
-e AWS_ACCESS_KEY_ID=<aws_access_key> \
-e AWS_SECRET_ACCESS_KEY=<aws_secret_key> \
...
    Note: Using Hybrid DNS Update with BlueCat Overlay for Microsoft
    If you are using Hybrid DNS Update with BlueCat Overlay for Microsoft, Hybrid DNS Update includes APIs that can also make updates to Microsoft DNS and Microsoft DHCP. By default, the DHCP APIs are not available using the standard docker run command. To enable the additional network and IP addresses APIs that are available in this configuration, specify the following additional environment variable in the docker run command:
    • SERVICE=ALL
    Note: If you are using RHEL with SELinux controls enabled, you must add a :Z option to the end of the path of any mapped volume. This modifies the SELinux label of the directory that is mounted to the container and should not be used with the system directories that are used with other applications, such as the /home directory.
Hybrid DNS Update contains a configuration file within /bluecat_gateway/workflows/Hybrid\ DNS\ Update/config/config.ini that is updated by the Hybrid DNS Update installation workflow. In managed environments where the Hybrid DNS Update container is deployed automatically and must be stateless, the following configuration parameters can be passed in as environment variables in the docker run command:
  • SERVICE_USERNAME—name of the BlueCat Gateway user that will be used to provide privilege elevation.
  • SERVICE_PASSWORD—encrypted password for the BlueCat Gateway user that will be used to provide privilege elevation.

When the configuration parameters are passed in as environment variables, the corresponding values in the configuration file are ignored. To update the configuration provided in the environment variables, you must delete and redeploy the Hybrid DNS Update container.