Set up desired states and remediation in VMware Tanzu Guardrails by using custom templates in your Git repository

You can use the desired state worker in Tanzu Guardrails to set up and enforce a desired state on your cloud account by using custom desired state templates from your GitHub or GitLab repository. The repository can be on-premises or in the cloud.

The desired state template is an SLS file that you store in your GitHub or GitLab repository, and is under version control.

A custom desired state template can:

  • Configure your public cloud accounts to a desired state.
  • Detect drifts from the desired state of the resources in your accounts.
  • Remediate the drifts from the desired state.

The desired state worker:

  • Is a Docker container image that hosts a runtime environment.
  • Requires the desired state worker group that you must create and deploy with Tanzu Guardrails in Tanzu Hub.
  • Runs your custom desired state template to enforce the desired state that the template defines.

The desired state worker downloads the desired state template from your Git repository and applies it to your cloud account. It can run your custom desired state template in monitor mode or enforcement mode.

Where to begin

Before you can run the desired state worker to remediate drift findings, you must:

  1. Verify your permissions in Tanzu Hub.
  2. Learn how to create a custom desired state template.
  3. Learn how to use your custom desired state templates with the desired state worker.
  4. Create a virtual machine where the desired state worker will reside, and install Docker on that virtual machine.
  5. Create a GitHub or GitLab repository that the virtual machine can access.
  6. Create a personal access token in your GitHub or GitLab repository.
  7. Create a desired state worker group.
  8. Create an API token in VMware Cloud Services.
  9. Verify that you have credentials for your AWS account or Azure subscription.

The following sections show you how.

When using the desired state worker, be aware of the following limitations.

  • You must only create one desired state worker at a time, even if the worker management provides the option to create multiple workers.
  • To view the logs from the Docker container, use the command docker logs <container_id> -f. An option does not exist to view the logs of the desired state worker in Tanzu Guardrails or Tanzu Hub.
  • If the desired state worker fails to start and reports a registration failure, be sure that you are not changing the worker. Stop the worker and start it again with a new name. If it still fails, delete or disable the worker group and create a new worker group, and attempt to start it again with a new worker ID.
  • If a request to the worker times out, delete or disable the worker group and create a new worker group, and attempt to start it again with a new worker name.

Verify your permissions

Before you can create the desired state worker group and run custom templates, you must have the correct permissions.

The credentials associated with the desired state worker depend on your credentials in Tanzu Hub, Tanzu Guardrails, and your GitHub or GitLab repository.

Role in Tanzu Hub Create or update desired state workers View desired state workers Trigger desired state remediation
Guardrails Admin No Yes Yes
Secure State Admin Yes Yes No
Guardrails User No Yes No

If you don’t have the correct permissions, actions such as edit, create, and the ability to associate accounts, are not available.

For more information about roles and permissions in Tanzu Hub, refer to Setting up users and projects for VMware Tanzu Hub.

Create a custom desired state template

The quickest way to create a desired state template and store it in your Git repository, is to start with a template that Tanzu Guardrails provides.

  1. Determine the desired state that you must enforce in your cloud accounts.

    For example, to create a desired state that enables or verifies the presence of AWS Web ACL attached to a given IP set that must be blocked, use the desired state template named Create or verify AWS Web ACL to block malicious ip set.

  2. In Tanzu Hub, click Guardrails > Policies.

  3. On the Templates card, click View Templates.
  4. To locate the template that you need, use the search area and select the provider such as AWS, enter any key words, and press Enter.
  5. When you find the desired state template that you need, expand the double arrows and review the code in the template.
  6. Copy the code from the desired state template and save it as an SLS file in your GitHub or GitLab repository.
  7. Modify the SLS file as needed for your own cloud account.

    You will use your SLS file with the desired state worker to remediate desired state drift findings.

  8. When you run the desired state with the custom template SLS file, you will provide the inputs to the template that meet the needs of your own cloud account.

Create a virtual machine and install Docker

In your AWS cloud account or Azure subscription, create a virtual machine where the desired state worker will reside, and install Docker on that virtual machine.

  1. Create a Linux or Windows virtual machine.
  2. Install the Docker engine on the virtual machine. Refer to the documentation at https://docs.docker.com/engine/install/.
  3. Verify the Docker engine by running the command docker –version.
  4. Get the desired state worker image from the Docker repository by running the command docker pull <remote_worker_image_path>. The location can be a local repository.

    If you plan to pull VMware images from a public Docker repository, make sure that you have a login for Docker.

  5. Start the Docker image container by running the docker run remoteworker -name <worker_name> command. The full command is the following script, and you provide the variables.

    docker run -it remoteworker -name <worker_name>
    -e WORKER_GROUP_ID=<worker_group_id>
    -e CSP_ENDPOINT_URL=https://console.cloud.vmware.com
    -e ARIA_HUB_URL=https://api.mgmt.cloud.vmware.com
    -e REFRESH_TOKEN={REFRESH TOKEN}
    -e AWS_ACCESS_KEY_ID={AWS ACCESS KEY ID}
    -e AWS_SECRET_ACCESS_KEY={AWS SECRET ACCESS KEY}
    -e AWS_IAM_ASSUME_ROLE_NAME={AWS IAM ASSUME ROLE NAME}
    -e AZURE_CLIENT_ID={AZURE_CLIENT_ID} -e AZURE_CLIENT_SECRET={AZURE_CLIENT_SECRET}
    -e AZURE_TENANT_ID={AZURE_TENANT_ID} -e GIT_PERSONAL_TOKEN={GIT_PERSONAL_TOKEN}
    

    The worker group ID and refresh token appear in the VMware Tanzu Guardrails user interface.

    You will use this script to start the desired state worker.

Create a Git repository and a personal access token

You must create a Git repository that the virtual machine and the desired state worker on the virtual machine can access.

  1. In your GitHub or GitLab account, create a repository.
  2. Store your custom desired state template in the Git repository.
  3. Create a personal access token so that when the desired state worker runs, it can access the repository.

    For example, in GitHub, go to Settings > Developer Settings > Personal access tokens, and create a token.

You will use the ID that the personal access token provides to communicate with the Git repository.

Create an API token

Create an API token in VMware Cloud Services. You will use the API token to start the desired state worker.

  1. In Tanzu Hub, click your user name, and click My Account.
  2. Click the API Tokens tab, click Generate a New API Token, enter the information, and click Generate.

You will use the API token in the command that starts the desired state worker.

Set up your AWS or Azure credentials

To start the desired state worker group, you must have user credentials in AWS or Azure.

AWS credentials required Azure credentials required
Multiple Amazon AWS regions - Refresh token, which is the API token
- AWS access key
- AWS secret key
- AWS IAM assume role name
- Git Personal token
Multiple Microsoft Azure regions - Refresh token, which is the API token
- Azure Client ID
- Azure Client secret
- Azure tenant ID
- Git Personal token

For example, for AWS:

  1. Create a user account in AWS or Azure, or use your existing user account.

    You configure the target account in Tanzu Guardrails.

  2. Create a role in the target account where you intend to create the desired state.

    Your user role in AWS or Azure will assume the role that you create in the target account to start the desired state worker.

The process is similar for an Azure subscription that will create the desired state. The Azure subscription must have access to the Azure client ID, client secret, and tenant ID.

Create the desired state worker group

To set up the desired state and enforce it by using the custom desired state templates in your own GitHub or GitLab repository, you must create a worker group. The worker group includes the worker that gets deployed to the Docker image container in your cloud account. Then, you deploy the desired state worker group.

To create the desired state worker group and deploy it, follow these steps.

  1. In Tanzu Hub, click Guardrails > Worker Groups.
  2. Create a desired state worker group.
    1. Click the Desired State Worker Groups tab.
    2. Click New Desired State Worker Group, and provide a name and description. Then, click Next.
  3. Deploy the desired state worker group.

    1. On the Deploy Worker Group page, copy the worker deployment script.

      The script uses the Docker run command to perform the remediation.

      • You will run the script on your Docker container image.
      • Before you run the script, you must enter the actual values into the script for your worker deployment.
      • If you plan to pull VMware images from a public Docker repository, make sure that you have a login for Docker.
    2. To deploy the desired state worker group, click Finish.

      After the worker group gets deployed, you can view the properties of the worker group and the workers that got deployed.

  4. To start the desired state worker, go to your Docker container, and run the script that you copied.

    1. Verify that your Docker container is running.
    2. Open the command line.
    3. Paste the desired state worker deployment script that you copied into the command line, and replace the placeholder values with actual values.

      docker run -it remoteworker -name <worker_name>
      -e WORKER_GROUP_ID=<worker_group_id>
      -e CSP_ENDPOINT_URL=https://console.cloud.vmware.com
      -e ARIA_HUB_URL=https://api.mgmt.cloud.vmware.com
      -e REFRESH_TOKEN={REFRESH TOKEN}
      -e AWS_ACCESS_KEY_ID={AWS ACCESS KEY ID}
      -e AWS_SECRET_ACCESS_KEY={AWS SECRET ACCESS KEY}
      -e AWS_IAM_ASSUME_ROLE_NAME={AWS IAM ASSUME ROLE NAME}
      -e AZURE_CLIENT_ID={AZURE_CLIENT_ID} -e AZURE_CLIENT_SECRET={AZURE_CLIENT_SECRET}
      -e AZURE_TENANT_ID={AZURE_TENANT_ID} -e GIT_PERSONAL_TOKEN={GIT_PERSONAL_TOKEN}
      

      Replace the worker name with the name of your desired state worker.

      For AWS, replace the following values:

      • API token: REFRESH_TOKEN={ENTER REFRESH TOKEN}

        The refresh token is the API token that you generated in the VMware Cloud Services user account.

      • AWS access key ID: AWS_ACCESS_KEY_ID={ENTER AWS ACCESS KEY ID}

      • AWS secret access key: AWS_SECRET_ACCESS_KEY={ENTER AWS SECRET ACCESS KEY}
      • AWS IAM role to assume: AWS_IAM_ASSUME_ROLE_NAME={ENTER AWS IAM ASSUME ROLE NAME} For Azure, replace the following values:

      • Azure Client ID: AZURE_CLIENT_ID={ENTER AZURE_CLIENT_ID}

      • Azure Client secret: AZURE_CLIENT_SECRET={ENTER AZURE CLIENT SECRET}
      • Azure tenant ID: AZURE_TENANT_ID={ENTER AZURE_TENANT_ID}
      • Git Personal token: GIT_PERSONAL_TOKEN={ENTER GIT PERSONAL TOKEN}
  5. Press Enter to run the command and start the desired state worker.
  6. The desired state creation completes in the worker and the findings get reported in Tanzu Guardrails.

Run your custom desired state template with the worker group

You can run your custom desired state template from the Tanzu Guardrails summary page.

  1. In Tanzu Hub, click Guardrails > Summary.
  2. In the Key Actions area, click Apply Templates.
  3. Select the cloud provider, the account, and region. Then, click Next.
  4. Select the desired state templates.

    1. For the template location, select External Repository.
    2. Enter the file path to your GitHub or GitLab repository.
    3. Provide the Git branch.
    4. Provide the Git file path and <file_name>.sls where your custom desired state template SLS file resides.
    5. For the version of the template, you can select Retrieve latest version or enter a Git commit ID.
    6. For the template category, select the category that exists in the desired state template meta data, then click Next.

      Depending on the template you are using, the category can be: Bootstrap, Config, Cost, Custom, Network, or Security.

      For example, this desired state template uses the SECURITY category:

      META:
        name: Create or verify AWS Web ACL to block malicious ip set
        provider: AWS
        category: SECURITY
        subcategory: Reference
        template_id: 3b.aws_wacl.1
        version: v1
        description: Enables or verifies the presence of Web ACL attached to given IP set which needs to be blocked. The default name of the WebACL is "web-acl-block-malicious-ip-set". A web access control list (web ACL) gives you fine-grained control over all of the HTTP(S) web requests that your protected resource responds to.
      
      
  5. Provide inputs for the desired state template, then click Validate Inputs, and click Next.

  6. To enforce the desired state template on your cloud accounts, click the Enforce card.

    Tanzu Guardrails directs you to the list of desired states for the desired state templates. In the list, you can verify that the desired state is created.

  7. Click the link to the desired state, click the Inputs tab, and review the inputs for the template.

    The template version or the Git commit ID appears in the list of inputs.

  8. If needed, you can apply another version of the template by clicking Apply New Template Version.

    1. In the new version, select either Retrieve latest version or enter a Git commit ID, and click Next.
    2. Update the inputs for the new version of the template.
    3. Click Save Changes.
  9. On the desired state, you can take several actions.
    1. To review the results, including the worker group name or ID, click Results History.
    2. To view the accounts associated with the desired state, click Accounts.
    3. To view the desired state template in the Git repository, click the link to the desired state template.
  10. To view the desired state worker running, log into the machine where the worker group resides in the Docker image container.

    The command that runs on the worker group is the same docker run command that appeared in the script when you created the worker group.

  11. To confirm what ran, review the logs for the desired state worker.

    If errors occur, refer to the list of limitations described earlier in this topic.

What to do next

Review the drift findings for your account to ensure that the open findings get resolved. Click Guardrails > Findings, and resolve the drift findings in priority order according to the attention score.

Parent topic:Define and apply governance policies in VMware Tanzu Hub

check-circle-line exclamation-circle-line close-line
Scroll to top icon