• Build a Docker image from source.

• Push the image to a registry.

• Update a K8s deployment with the new image.

The playbook structure would be:

- name: Build image...
- name: Push to a registry...
- name: Update deployment...

Now, your boss comes and says "don't publish anything before I tell you so". We add tags to run tasks separately:

- name: Build image...
  tags: [build]
- name: Push to registry...
  tags: [publish]
- name: Update deployment...
  tags: [deploy]

Almost there. We can do everything we want, but we need to specify multiple tags. You can create a serious mess this way. So, the third and final approach is to populate a tag to every tag we're dependent on:

- name: Build image...
  tags: [build, publish, deploy]
- name: Push to registry...
  tags: [publish, deploy]
- name: Update deployment...
  tags: [deploy]

Here you go. If you want to deploy all - use tag 'deploy'. For build only - 'build'. That would be it, except for one caveat. We don't want to run unnecessary tasks. Theoretically - it shouldn't be a problem. Ansible modules are meant to be idempotent. It means - we can run a task any number of times we want - the result should be the same. But sometimes we're wasting our time. Then it would be good to have a 'when' clause to check whether running a task is really necessary.

And one bonus thing. If you create a complex playbook with multiple targets, having a default workflow, without tags makes no sense. For example, you don't want to build something then destroy it. In that case - use a default tag guard:

 pre_tasks:
    - name: Default tag guard
      assert:
        that: "'all' not in ansible_run_tags"
        msg: No default tasks here.

Thanks for the audience. I hope I managed to write something which is not obvious for everyone.

TL;DR

I’m going to create a simple workflow for deploying a Terraform stack on AWS using GitHub Action. I will setup OIDC authentication between GitHub and AWS.

Prerequisites

We will need:

• a simple, working Terraform project,

• an AWS account.

• a GitHub account.

AWS identity provider

Please, create it according to the guide: https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws

It needs to be done once per AWS account.

S3 backend

It’s not going to work with a local state file. Let’s prepare all required items. I’m going to use Terraform code. Please mind it is not a part of the project you’re going to deploy.

Bucket

Just create a bucket with permissions.

resource "aws_s3_bucket" "state-bucket" {
  bucket = local.bucket_name
}

resource "aws_s3_bucket_versioning" "vers" {
  bucket = aws_s3_bucket.state-bucket.id
  versioning_configuration {
    status = "Enabled"
  }
}

I have a local variable describing the bucket name.

IAM

I’m going to use the same permissions for backend and for AWS provider. You probably should separate these roles for non-lab environments.

Local user

Despite - we’re going to use OIDC - I still want and user to run it locally.

data "aws_iam_policy_document" "project_policy" {
  statement {
    actions = [
      "s3:ListBucket"
    ]
    resources = [aws_s3_bucket.state-bucket.arn]
  }

  statement {
    actions = [
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject"
    ]
    resources = [
      "${aws_s3_bucket.state-bucket.arn}/*/terraform.tfstate",
      "${aws_s3_bucket.state-bucket.arn}/*/terraform.tfstate.tflock"
    ]
  }
}

resource "aws_iam_user" "project_user" {
  name = "${var.project_name}-user"
}

resource "aws_iam_user_policy" "project_user_policy" {
  user   = aws_iam_user.project_user.id
  policy = data.aws_iam_policy_document.project_policy.json
}

Now - add the permissions which allow to build you infra. They are a little bit too wide. Please adjust them to your needs.

resource "aws_iam_user_policy_attachment" "ec2-full" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
}

resource "aws_iam_user_policy_attachment" "vpc-full" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/AmazonVPCFullAccess"
}

resource "aws_iam_user_policy_attachment" "ssm-ro" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess"
}

resource "aws_iam_user_policy_attachment" "iam-ro" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/IAMReadOnlyAccess"
}

You will need an access key for the user to use it locally

Role

OIDC needs an IAM role.

data "aws_iam_policy_document" "sts_policy" {
  statement {
    effect = "Allow"
    principals {
      type        = "Federated"
      identifiers = ["arn:aws:iam::<AWS account ID>:oidc-provider/token.actions.githubusercontent.com"]
    }
    actions = ["sts:AssumeRoleWithWebIdentity"]
    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values = [
        "repo:<GitHub account>/<Repo>:ref:refs/heads/main"
      ]
    }
  }
}


resource "aws_iam_role" "project_role" {
  assume_role_policy = data.aws_iam_policy_document.sts_policy.json
  name               = "${var.project_name}-role"
}

resource "aws_iam_role_policy" "project_role_attach" {
  role   = aws_iam_role.project_role.id
  policy = data.aws_iam_policy_document.project_policy.json
}

You need to adjust the following parameters:

• AWS account ID,

• GitHub user or organization,

• The repo name.

The last resource allows the role to access the bucket. You still need the resources access. You can copy the code from user changing aws_iam_user_policy_attachment to aws_iam_role_policy_attachment.

That’s it. You can deploy the resources manually.

Setup the S3 backend for you project

Now create or update the backend setup for your project.

terraform {
  backend "s3" {
    bucket       = "<bucket-name>"
    key          = "<stack>/terraform.tfstate"
    use_lockfile = true
    region       = "eu-central-1"
  }
}

Replace bucket name, and “folder” in the bucket. I have multiple stacks in my project - each with a separate state. If your project is live already, use terraform init -migrate-state. If i’s a fresh one - just terraform init'

Workflow setup

Crate a YAML file in .github/workflows/

---
name: Net
on:
  push:
    branches: ["main"]
    paths:
      - net/**

permissions:
  id-token: write
  contents: read

jobs:
  make_key:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: net/
    steps:
      - uses: actions/checkout@v6
      - uses: aws-actions/configure-aws-credentials@v5
        with:
          role-to-assume: arn:aws:iam::<AWS account id>:role/tf-infra-role
          aws-region: eu-central-1
      - uses: hashicorp/setup-terraform@v3

      - run: terraform init -input=false
      - run: terraform plan
      - run: terraform apply -auto-approve

A quick explanation:

• the workflow runs when you push to the ‘main’ and something in net/ subdir is changed. As I said - I have multiple stacks with multiple workflows.

• “permissions” - required to handle OIDC.

• “working-directory” - skip it if you run your project in the root.

• “uses: aws-actions/configure-aws-credentials” - setups AWS connectivity. Use your actual account id.

• Then terraform stuff goes. I know. I should have an approval after plan…

If everything went right - after next push you infra should built. You always can run terraform destroy locally.

References

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html

https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws

VPC

Of course, to create a VDP - we need VDP:

resource "aws_vpc" "min_vpc" {
  cidr_block                       = "10.0.0.0/16"
  assign_generated_ipv6_cidr_block = true
  enable_dns_support               = true
  enable_dns_hostnames             = true
}

We need to specify:

• IP range. (Do you have any idea why people hate 172.16/12?)

• IPv6 range. It’s assigned automatically.

• DNS support. If the instances uses Amazon DNS. Actually true is default.

• DNS hostnames. If true - instances get funny hostnames in amazonaws.com.

Subnet

Every VPC needs at least one subnet.

resource "aws_subnet" "pub" {
  vpc_id                          = aws_vpc.min_vpc.id
  cidr_block                      = cidrsubnet(aws_vpc.min_vpc.cidr_block, 8, 0)
  ipv6_cidr_block                 = cidrsubnet(aws_vpc.min_vpc.ipv6_cidr_block, 8, 0)
  assign_ipv6_address_on_creation = true
}

• vpc_id - the parent VPC.

• cidr_block - the address range of the segment. Similar for IPv6. We don’t specify it manually - instead we’re using cidrsubnet function. Which cuts a network segments to a smaller one.

Gateway

Like every gateway - traffic goes through it.

resource "aws_internet_gateway" "gw" {
  vpc_id = aws_vpc.min_vpc.id
}

Nothing fancy. Just VPC id.

Routing table

Just routes everything to the gateway.

resource "aws_route_table" "rt" {
  vpc_id = aws_vpc.min_vpc.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.gw.id
  }
  route {
    ipv6_cidr_block = "::0/0"
    gateway_id      = aws_internet_gateway.gw.id
  }
}

Route table association

Connects a route to a subnet.

resource "aws_route_table_association" "pub_assoc" {
  subnet_id      = aws_subnet.pub.id
  route_table_id = aws_route_table.rt.id
}

Final words

That’s more or less it. You can remove IPv6 related lines. You’ll probably gonna need a security group. I’ll describe it along with an instance example - soon.

References

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/subnet

https://developer.hashicorp.com/terraform/language/functions/cidrsubnet

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/internet_gateway.html

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route_table

We’re going to use:

• S3 bucket with versioning and encryption.

• DynamoDB table for locking.

• Separate user for backend access.

• Separate user backend user for each project.

To follow the the guide you gonna need:

• AWS account. Root or enough privileges to manage users and create resources.

• aws cli installed.

• Terraform installed.

You also need to know:

• The project name.

• The bucket name. They need to be unique globally. It would be useful to find your favorite name and add a random suffix. Like string generated with the command openssl rand -hex 3. Or - you can read guide mentioned in links.

Creating AWS resources

First - login to you AWS admin account. You can create your bucket now. Adjust your bucket name and region.

aws s3api create-bucket \
  --bucket tf-state-xxxx \
  --region eu-central-1 \
  --create-bucket-configuration LocationConstraint=eu-central-1

Enable bucket versioning.

aws s3api put-bucket-versioning \
  --bucket tf-state-xxxx \
  --versioning-configuration Status=Enabled

Then encryption.

aws s3api put-bucket-encryption \
  --bucket  tf-state-xxxx\
  --server-side-encryption-configuration '{
    "Rules": [{
      "ApplyServerSideEncryptionByDefault": {
        "SSEAlgorithm": "AES256"
      }
    }]
  }'

Create DynamoDB table:

aws dynamodb create-table \
  --table-name terraform-locks \
  --attribute-definitions AttributeName=LockID,AttributeType=S \
  --key-schema AttributeName=LockID,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

Create user

Please create a file from following template, replacing bucket name, project name, client id and region. The name used in the example is. projectA-policy.json. Feel free to adjust.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowS3StateAccess",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::<bucket-name>/<project-name>/*"
    },
    {
      "Sid": "AllowS3ListPrefix",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::<bucket-name>",
      "Condition": {
        "StringLike": {
          "s3:prefix": "<project-name>/*"
        }
      }
    },
    {
      "Sid": "AllowDynamoDBLocking",
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:DeleteItem",
        "dynamodb:UpdateItem"
      ],
      "Resource": "arn:aws:dynamodb:eu-central-1:<client-id>:table/terraform-locks"
    }
  ]
}

create the user:

aws iam create-user --user-name projectA-tfstate

Attach the policy.

aws iam put-user-policy \
  --user-name projectA-tfstate \
  --policy-name projectA-tfstate-policy \
  --policy-document file://projectA-policy.json

Create access key:

aws iam create-access-key --user-name projectA-terraform

Create an aws cli profile.

aws sonfigure --profile projectA-terraform

Start using it

Create a Terraform file. For example backend.tf.

terraform {
  backend "s3" {
    bucket         = "tf-state-xxxx"
    key            = "projectA-terraform/terraform.tfstate"
    region         = "eu-central-1"
    profile        = "projectA-terraform"
    use_lockfile   = true
    encrypt        = true
  }
}

If you’re lucky - you can run terraform init without errors now.

Links

https://developer.hashicorp.com/terraform/language/backend/s3

https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli

https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html

First, you have to remember your password. Store it in the .vault_password file in your home dir. Just remember to make it readable only for you.

chmod go-rwx ~/.vault_password

Now, tell Ansible to use the file. You can do it in ansible.cfg.

[defaults]
vault_password_file = ~/.vault_password

We’re going to keep the secrets and private vars outside our repo. So - we’re going to create a kind of inventory which contain only variables.

mkdir -p ~/my_ansible_secrets/group_vars/all/

Then make ansible using it. We will add the new inventory to a config. Ansible don’t mind having multiple inventories. Now, our ansible.cfg looks like that

[defaults]
inventory = testinv.yaml, ~/my_ansible_secrets
vault_password_file = ~/.ansible_password

Now’s time to encrypt.

ansible-vault encrypt_string -n my_secret 'i wont tell' >> ~/my_ansible_secrets/group_vars/all/secrets.yaml

Please look into the file. Adding minuses at the beginning of an YAML file won’t hurt.

---
my_secret: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66626630323438343166393164343162366634346362386163623036613333343465323635393839
          6638623963313135616434313165646232346132303338320a616137303230623436343031643436
          36613135363366303035653731616561333439383662383433346537643139653663396339346435
          6661313739643036360a393635313837346536633136303932316638386463343465376238373532
          6338

Time to test:

TADA! One more thing - let’s get rid of the ugly warning. Just create a a dummy inventory file.

 echo '[all]' > ~/my_ansible_secrets/dummy.ini

That’s it. You really should use and real password manager… Anyway - you probably still will want to keep some private vars - like username - outside your official repo. You can use “vars only inventory” technique whenever you need.

For testing purpose - you can use the environment created there: https://fossexperience.hashnode.dev/ansible-hello-world

So - let’s take a look at the code:

---
- hosts: testgroup
  tasks:
    - name: gather
      command: lsusb
      register: result

    - name: make report
      copy:
        dest: report.txt
        content: |
          {% for h in ansible_play_hosts %}
          {% for l in hostvars[h].result.stdout_lines %}
          {{h}};{{l | quote}}
          {% endfor %}
          {% endfor %}
      delegate_to: localhost
      run_once: true

In the '“gather” task we collect whatever we want. In this case - USB devices. And save it in the “result” variable.

The “make report” task is almost ‘normal’ copy. We learn two things:

• We can use content instead of src. I our case it is a Jinja2 template

• We can access other hosts variables via hostvars.

Let’s explain the template now.

• The outer loop. It just loops over all hosts in ansible_play_hosts built-in variable. And assigns it to h.

• The inner loop. Loops over result.stdout_lines. Which contains the command output nicely split to lines.

We’re delegating the “copy” command to the controller. And we run it only once.

One more thing. Always quote string you’re unsure of. It helps you to avoid real problems. Like crappy CSV with messed fields. Or code injection.

Good luck with with data collection. And wish good luck with data analysis to your boss. She/He’s gonna need it…

Install Ansible

I assume you have python3 / pip / virtualenv working on your system. We don’t want to mess up, so we’re going to use virtualenv.

virtualenv venv
. venv/bin/activate
pip install ansible

That’s it. You can check it out typing ansible --version.

Config file.

Create a config file. ansible.cfg in your working directory.

[defaults]
inventory = testinv.yaml
interpreter_python = auto_silent
nocows = true

Let me explain.

[defaults] - most of interesting settings goes to this section.

inventory - our inventory. We’ll create it in the next step.

interpreter_python - suppresses warning about python interpreter.

nocows - suppresses using cowsay for displaying messages. Use at your own risk. ;)

Inventory

Let’s create testinv.yaml file. You can also use ini format. I prefer yaml. Up to you.

---
all:
  children:
    testgroup:
      hosts:
        testhost:
          ansible_connection: local

all - the root group name. Everything goes there.

children - a group can have subgroups. List them under children

testgoup - our actual group name

hosts - of course group can contain hosts…

testhosts - a host. A kind of fake hosts for testing purpose. Normally the names must be resolvable in DNS. Or in /etc/hosts. Or be IP addresses.

ansible_connaction - Describes way of connecting the host. local means localhost. Everything will be executed locally. It means the name from previous line doesn’t really matter.

The first playbook

Let’s create the file - hello.yaml'. Yes. While using ansible - you’re and yaml developer.

---
- hosts: testgroup
  tasks:
    - debug:
        msg: Hello World!

Quite obvious. The playbook is executed on all boxes listed in the testgoup group. We’re going to display “Hello World!” message.

Run it

The command is simple:

ansible-playbook hello.yaml

If you’re lucky and did not make any silly mistake - you’ll see:

That’s it. I hereby declare you and automation guru. Congratulations.