Policy Deployment

This document outlines how IAM policies and applications are registered to the TAM environment.

Policy file structure

The GitHub repository contains the following base folders:

github: This folder contains the workflow files necessary for package and application registration.
tam/bundles: This folder holds the metadata required for application registration, including namespace and versions (prod and stage), formatted as JSON files. The version field is optional.
Policies: This folder includes the rego folder, which contains policy Rego files, and a test folder, which contains test Rego policy files.
policy-config: This contains a policy.json file, which contains a list of policy details. This can have all the package register optional params as referred in the docs. Consumer Key and Consumer Secret should not be added in the policy-config. Instead, these details will be passed from GitHub sharable Actions.
```
"policy-config": [{
  "packageNamespace": "com.cms.platform",
  "pathToFiles": "tam/policies/platform/rego",
  "pathToTestFiles": "tam/policies/platform/test",
  "remoteDataSourceUrls": "localhost:8080",
  "remoteDataSourceExpirations": "10",
  "remoteDataSourceScopes": "app"
}]
```

ETools Artifactory service account creation

You will need an ETools Artifactory service account to store artifact versions used during deployment.

Stage deployment flow (can be customized as per user needs)

Package registration:
When changes are pushed to the main branch and the path matches the policies, the packages affected by the commit will be registered to the TAM stage environment, and the latest package version will be updated in the GitHub version repository.
Workflow dispatch:
The list of input packages will be registered to the TAM stage environment, and the latest package version will be updated in the GitHub version repository.
Application registration:
On approval, the application will be registered to the target environments. You can streamline the deployment stages based on your needs.

Production deployment flow (can be customized as per user needs)

Package registration:
Workflow dispatch from the release branch. The list of input packages will be registered to the TAM prod environment, and the latest package version will be updated in the GitHub version repository.
Application registration:
On approval, the application will be registered to the target environments.

Permissions

Provide the following GitHub permissions. These are required to download the GitHub artifact:

permissions:
  contents: read
  actions: read

To achieve on-push package registration events, you need to use the checkout option with fetch-depth: 0.

Pre-setup

Option 1: Git repository for versions

Create a new repository iam-policy-versions to store the policy versions. This will be retrieved and uploaded as part of the IAM policy CI/CD workflow.

Add two empty JSON files to the repository: prod-version.json and stage-version.json.
Create a GitHub App with the permission “Read and write access to code” on the iam-policy-versions repository.
Once the app is created:
- Note down the App ID and create a GitHub Secret with the key APP_ID.
- Create a private key and store it in GitHub secrets with the key APP_PRIVATE_KEY.

Option 2: ETools Artifactory

Create an ETools Artifactory to store the stage and prod latest versions.

Manually upload the latest version as version.zip in the artifact.
(How to create ETools repo can be documented separately.)

Option 3: Application environment storage

Store versions in the application environment (for example, S3 or Storage Account).

GitHub environments (as per user needs)

You can configure the following GitHub environments:

dev
qa
stage
prod

GitHub environment secrets

Configure the following environment secrets:

tam_application_reg_client_id
tam_application_reg_client_secret

GitHub repository secrets

Configure the following repository secrets:

TAM_APP_ARTIFACTUSERNAME
TAM_APP_ARTIFACTPASSWORD
TAM_PCKG_REG_STAGE_CLIENT_SECRET
TAM_PCKG_REG_PROD_CLIENT_SECRET

GitHub repository variables

Configure the following repository variables:

TAM_PCKG_REG_STAGE_CLIENT_ID
TAM_PCKG_REG_PROD_CLIENT_ID

Sharable workflow actions

Package register

Use the sharable Package Register action in your workflow:

{% raw %}

- name: PackageRegister
  id: package_register
  # Has to be moved to trimble-oss
  uses: trimble-oss/tam-registration/.github/actions/package-register@2.1.5
  with:
    ENVIRONMENT: ${{ env.environment }}
    STACK_NAME: ${{ env.tam_environment }}
    CLIENT_ID: ${{ env.client_id }}
    CLIENT_SECRET: ${{ env.client_secret }}
    TRIMBLE_ARTIFACTORY_USERNAME: ${{ secrets.TAM_APP_ARTIFACTU }}
    TRIMBLE_ARTIFACTORY_PASSWORD: ${{ secrets.TAM_APP_ARTIFACTP }}
    PACKAGE_LIST: ${{ inputs.policy }}

{% endraw %}

Application register

Use the sharable Application Register action in your workflow:

{% raw %}

- name: application registration
  uses: trimble-oss/tam-registration/.github/actions/application-register@dev/TACM-1328
  with:
    NAME: authz
    TAM_ENVIRONMENT: ${{ env.tam_environment }}
    CLIENT_ID: ${{ env.client_id }}
    CLIENT_SECRET: ${{ secrets.client_secret }}
    ARTIFACT_RUN_ID: ${{ inputs.run_id }}
    APP_REGISTRATION_JOB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{% endraw %}

In the example below, the CLIENT_SECRET is read from AWS SSM and masked to ensure it does not appear in the GitHub logs:

- name: Set environment from SSM
  run: |
    CLIENT_SECRET_PARAMETER_NAME="/dev/tam_client_secret"
    client_secret=$(aws ssm get-parameter --name $CLIENT_SECRET_PARAMETER_NAME --with-decryption --query "Parameter.Value" --output text)
    echo "client_secret=$client_secret" >> $GITHUB_ENV
    echo "::add-mask::$client_secret"