config0.yml

OpenTofu workflows via stacks are executed through a launch configuration file - config0/config0.yml.

Configuration Sections

The config0.yml file contains these major sections:

global:
  arguments:
    <arg 1>
    <arg 2>
    <arg 3>
  ...
<automation category>:
  <stack alias configuration>:
    stack_name: <stack_name>
    arguments:
      <arg 1>
      <arg 2>
      <arg 3>
      ...

Global Arguments

Global arguments are variables provided to every stack within a project. These arguments drive the expression of the automation.

global:
  arguments:
    cloud_provider: aws
    region: us-east-1
    db_type: mysql
    sg_db_label: database
    sg_web_label: web

Field	Description
`global/arguments`	Stack arguments (variables) applied to all stacks in the project

Labels and Selectors

Labels and selectors work together to assign labels to resources and subsequently choose them for downstream operations. This pattern is similar to what is used in Kubernetes clusters.

Labels

Labels are key/value pairs attached to created resources.

In the example below, the first label general contains these key-value pairs:

environment → dev
purpose → test

labels:
  general:
    environment: dev
    purpose: test
  infrastructure:
    cloud: aws
    product: vpc
    app_tier: networking
  vehicle:
    car: bmw

These labels (general, infrastructure, and vehicle) will be applied to infrastructure resources like VPCs, subnets, security groups, and internet gateways:

infrastructure:
  vpc:
    stack_name: config0-publish:::aws_vpc_and_security_group
    arguments:
      eks_cluster: eval-ed-eks
      vpc_name: eval-ed-vpc
      main_network_block: 10.30.0.0/16
      tier_level: "2"
      enable_nat_gateway: true
      single_nat_gateway: true
      enable_dns_hostnames: true
      reuse_nat_ips: true
      one_nat_gateway_per_az: false
      tags: "mongo,database,stateful"
    labels:
      - general
      - infrastructure
      - vehicle

Selectors

Selectors are key/value pairs used to query the Config0 database and retrieve matching resources.

Notable query parameters for metadata matchSelectors:

labels - key/value “labels” for resource db query
keys - specific key,value pairs (not labels) used as part of the query
params - additional conditions/special fields for the query, including:
must_exist (True/False) - whether the query must return at least one value
resource_type - the specific resource type to query for

Example of selector definitions:

metadata:   
  labels:
    general: 
      environment: dev
      purpose: eval-config0
    infrastructure:
      cloud: aws
      product: eks
  matchSelectors:
    network_vars:
      labels:
        environment: dev
        purpose: eval-config0
        area: network
        region: eu-west-1
        cloud: aws
    eks_info:
      keys:
        provider: aws
        region: eu-west-1
        aws_default_region: eu-west-1
      params:
        resource_type: eks
      labels:
        environment: dev
        purpose: eval-config0
        cloud: aws

Selectors must be included for each stack - they are not global:

infrastructure:
  rds:
    stack_name: config0-publish:::aws_rds
    arguments:
      vpc_name: selector:::vpc_info::name
      sg_id: selector:::sg_info::sg_id
      subnet_ids: selector:::subnet_info::subnet_id:csv
      rds_name: eval-ed-rds
      allocated_storage: 14
      db_name: app
    selectors:
      - vpc_info
      - sg_info
      - subnet_info

Selector Syntax

The selector query syntax is:

<variable_name>:selector:::<selector_name>::<key_in_query>::<format>

Examples:

vpc_name:selector:::vpc_info::name
The variable vpc_name will be looked up through the selector vpc_info
The key name is returned from the selector result
String is the default format
subnet_ids:selector:::subnet_info::subnet_id::csv
The variable subnet_ids will be looked up through the selector subnet_info
The key subnet_id from results is returned
The format will be a string of subnet_ids separated by a comma (csv)

Specifying Stacks

Parameterized stacks are driven primarily through arguments and secondarily through environmental variables. Stacks are specified with the following components:

Automation Category

Stacks are categorized by automation category in the YAML configuration
Common examples: infrastructure, build, and deploy

Stack Alias

In each automation category, the stack is given an alias
Example: ecr_repo is an alias for stack name config0-publish:::ecr_repo

Stack Name

Stack names are referenced by username, stack_name, and optionally version:

<username>:::<stack_name>::<version>

Version formats:

Latest version (most common): config0-publish:::ec2_docker_host
Release version (most stable): config0-publish:::ec2_docker_host:0.0.1
Auto-incrementing version: config0-publish:::ec2_docker_host:5

Arguments

Variables used by the stack
Arguments drive the behavior of the stack

# Structure:
# <automation_category>
#   <stack_alias_setup>
#     stack_name: <stack_name>
#     arguments:
#       ...

infrastructure:
  ecr_repo:
    stack_name: config0-publish:::ecr_repo
    arguments:
      name: flask_sample
  dockerhost:
    stack_name: config0-publish:::ec2_docker_host
    arguments:
      size: t2.micro
      disksize: 25

Full Example

The following example creates an EKS cluster using an existing VPC. This provides end-to-end automation with a single entry point: the stack config0-publish:::aws_eks.

Full Example: EKS Cluster with Existing VPC

global:
  arguments: 
    aws_default_region: eu-west-1
  metadata:   
    labels:
      general: 
        environment: dev
        purpose: eval-config0
      infrastructure:
        cloud: aws
        product: eks
    matchSelectors:
      network_vars:
        labels:
          environment: dev
          purpose: eval-config0
          area: network
          region: eu-west-1
          cloud: aws
      eks_info:
        keys:
          provider: aws
          region: eu-west-1
          aws_default_region: eu-west-1
        params:
          resource_type: eks
        labels:
          environment: dev
          purpose: eval-config0
          cloud: aws

infrastructure:
  eks:
    stack_name: config0-publish:::aws_eks
    arguments:
      vpc_name: selector:::network_vars::vpc_name
      vpc_id: selector:::network_vars::vpc_id
      # vpc with NAT, private_subnet_ids is more secure
      subnet_ids: selector:::network_vars::public_subnet_ids:csv
      sg_id: selector:::network_vars::bastion_sg_id
      eks_cluster: eval-config0-eks
      eks_cluster_version: 1.25
      publish_to_saas: true
      # vpc with NAT, private_subnet_ids is more secure
      eks_subnet_ids: selector:::network_vars::public_subnet_ids:csv
      eks_node_role_arn: selector:::eks_info::node_role_arn
      eks_node_capacity_type: ON_DEMAND
      eks_node_ami_type: AL2_x86_64
      eks_node_max_capacity: 1
      eks_node_min_capacity: 1
      eks_node_desired_capacity: 1
      eks_node_disksize: 25
      eks_node_instance_types: 
        - t3.medium
        - t3.large
      cloud_tags_hash:
        environment: dev
        purpose: eval-config0
    spec:
      serialization:
        to_base64:
          arguments:
            - cloud_tags_hash
    metadata:
      labels:
        - general
        - infrastructure
      matchSelectors:
        - network_vars
        - eks_info