Deployment Overview

Relevant source files

The following files were used as context for generating this wiki page:

• iac-recert-engine/github-action.yaml
• iac-recert-engine/cronjob.yaml
• iac-recert-engine/cmd/ice/run.go
• iac-recert-engine/cmd/ice/root.go
• iac-recert-engine/internal/engine/engine.go
• iac-recert-engine/example.config.yaml

The IAC Recertification Engine (ICE) is designed to be executed on a schedule to scan repositories and manage recertification pull requests. It can be deployed in various environments, with the two primary methods being a GitHub Action and a Kubernetes CronJob. Both deployment strategies execute the same core application binary, ice, using the run command.

The engine's behavior is heavily configured through a central YAML file, which defines the target repository, authentication, scanning patterns, and PR generation strategies. This allows the deployment environment to be relatively simple, focusing only on scheduling the execution and providing the necessary credentials and configuration.

Sources: iac-recert-engine/github-action.yaml, iac-recert-engine/cronjob.yaml, iac-recert-engine/cmd/ice/run.go:13-15

Core Execution

Regardless of the deployment method, the core process is initiated by the ice run command. This command is the main entry point for the recertification process.

Sources: iac-recert-engine/cmd/ice/run.go:13

Execution Flow

The run command orchestrates the entire recertification workflow. It loads the configuration, sets up logging, initializes the main Engine, and triggers the Run method.

The following diagram shows the high-level flow initiated by the ice run command.

Load Config*: Reads and validates the configuration from a YAML file.
Sources: iac-recert-engine/cmd/ice/run.go:17-23

• Setup Logger: Initializes a zap logger, using a development logger if verbose_logging is true.
  Sources: iac-recert-engine/cmd/ice/run.go:29-32
• Initialize Engine: Creates a new Engine instance, which involves setting up the Git provider, scanner, analyzer, and other components.
  Sources: iac-recert-engine/cmd/ice/run.go:35-38, iac-recert-engine/internal/engine/engine.go:31-67
• Execute Engine.Run: The main logic loop that scans, analyzes, checks, groups, and processes files needing recertification.
  Sources: iac-recert-engine/cmd/ice/run.go:41, iac-recert-engine/internal/engine/engine.go:70-131

Configuration Loading

The application locates its configuration file using a specific order of precedence:

1. A path provided via the --config flag.
2. A path from the ICE_CONFIG_PATH environment variable.
3. A file named .ice.yaml in the user's home directory.

Sources: iac-recert-engine/cmd/ice/root.go:42-58

GitHub Action Deployment

A common way to deploy the engine is as a GitHub Action within the repository that needs to be scanned or a central management repository.

Sources: iac-recert-engine/github-action.yaml

Workflow Configuration

The provided github-action.yaml defines a workflow that runs on a schedule and can also be triggered manually.

name: IaC Recertification

on:
  schedule:
    - cron: '0 2 * * 0' # Weekly on Sunday at 2am
  workflow_dispatch:

jobs:
  recertify:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: '1.21'
        
    - name: Build ICE
      run: go build -o ice ./cmd/ice
      
    - name: Run Recertification
      run: ./ice run
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Sources: iac-recert-engine/github-action.yaml:1-25

Key Aspects

• Trigger: The workflow is scheduled to run weekly on Sunday at 2 AM and can also be started manually via workflow_dispatch.
  Sources: iac-recert-engine/github-action.yaml:4-7
• Execution Steps:
  1. The code is checked out.
  2. The Go environment is set up.
  3. The ice binary is built from the source.
  4. The ice run command is executed.
     Sources: iac-recert-engine/github-action.yaml:12-23
• Authentication: The GITHUB_TOKEN secret is passed as an environment variable to the ice run command. The engine uses this token to authenticate with the GitHub API. The auth.token_env configuration must be set to GITHUB_TOKEN.
  Sources: iac-recert-engine/github-action.yaml:24-25, iac-recert-engine/example.config.yaml:15-17

Kubernetes CronJob Deployment

For environments using Kubernetes, the engine can be deployed as a CronJob. This involves building a container image with the ice binary and deploying it with the necessary configuration and secrets.

Sources: iac-recert-engine/cronjob.yaml

CronJob Manifest

The cronjob.yaml manifest defines the schedule and the job template for running the engine.

apiVersion: batch/v1
kind: CronJob
metadata:
  name: iac-recert-engine
spec:
  schedule: "0 2 * * 0" # Weekly on Sunday at 2am
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: ice
            image: iac-recert-engine:latest
            args:
            - run
            env:
            - name: GITHUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: ice-secrets
                  key: github-token
            volumeMounts:
            - name: config-volume
              mountPath: /app/config.yaml
              subPath: config.yaml
          volumes:
          - name: config-volume
            configMap:
              name: ice-config
          restartPolicy: OnFailure

Sources: iac-recert-engine/cronjob.yaml:1-30

This diagram illustrates the relationship between the Kubernetes resources.

Key Aspects

• Schedule: The job is scheduled to run weekly on Sunday at 2 AM, matching the GitHub Action example.
  Sources: iac-recert-engine/cronjob.yaml:5
• Container: It uses a container image named iac-recert-engine:latest and executes the run command.
  Sources: iac-recert-engine/cronjob.yaml:12-15
• Configuration: The engine's configuration file is mounted from a ConfigMap named ice-config into the container at /app/config.yaml.
  Sources: iac-recert-engine/cronjob.yaml:23-28
• Authentication: The GITHUB_TOKEN is supplied as an environment variable from a Secret named ice-secrets.
  Sources: iac-recert-engine/cronjob.yaml:16-21

Deployment Configuration

Both deployment methods rely on a set of shared configurations defined in the main YAML file. The following global settings are particularly relevant to the deployment and execution environment.

Parameter	Description	Example Value	Source File
dry_run	If true, the engine will log the PRs it would create but will not perform any write operations (branch, commit, PR).	false	example.config.yaml:20
verbose_logging	If true, enables more detailed development-style logging.	true	example.config.yaml:22
default_base_branch	The default base branch to use for creating pull requests.	"main"	example.config.yaml:26
schedule.cron	A reference for the cron schedule, used for generating the CronJob manifest.	"0 2 * * 0"	example.config.yaml:70

The dry_run flag can be overridden at runtime with the --dry-run command-line flag.
Sources: iac-recert-engine/cmd/ice/run.go:50-51