Terraform Google Container VM Metadata Module

This module handles the generation of metadata for deploying containers on GCE instances.

This module itself does not launch an instance or managed instance group. It generates the necessary metadata to create an instance or MIG yourself. Examples of using this module can be found in the examples/ directory.

Compatibility

This module is meant for use with Terraform 0.13+ and tested using Terraform 1.0+. If you find incompatibilities using Terraform >=0.13, please open an issue. If you haven't upgraded and need a Terraform 0.12.x-compatible version of this module, the last released version intended for Terraform 0.12.x is v2.0.0.

Usage

module "gce-container" {
  source = "terraform-google-modules/container-vm/google"
  version = "~> 3.1"

  container = {
    image="gcr.io/google-samples/hello-app:1.0"
    env = [
      {
        name = "TEST_VAR"
        value = "Hello World!"
      }
    ],

    # Declare volumes to be mounted.
    # This is similar to how docker volumes are declared.
    volumeMounts = [
      {
        mountPath = "/cache"
        name      = "tempfs-0"
        readOnly  = false
      },
      {
        mountPath = "/persistent-data"
        name      = "data-disk-0"
        readOnly  = false
      },
    ]
  }

  # Declare the Volumes which will be used for mounting.
  volumes = [
    {
      name = "tempfs-0"

      emptyDir = {
        medium = "Memory"
      }
    },
    {
      name = "data-disk-0"

      gcePersistentDisk = {
        pdName = "data-disk-0"
        fsType = "ext4"
      }
    },
  ]

  restart_policy = "Always"
}

Then perform the following commands on the root folder:

• terraform init to get the plugins
• terraform plan to see the infrastructure plan
• terraform apply to apply the infrastructure build
• terraform destroy to destroy the built infrastructure

Inputs

{
  "command": "ls",
  "image": "gcr.io/google-containers/busybox"
}

Outputs

Container Options

Advanced container options, as described here, can be passed in as part of the container map.

The instance_with_advanced_options example also demonstrates this.

module "gce-advanced-container" {
  source = "terraform-google-modules/container-vm/google"
  version = "~> 2.0"

  container = {
    image = "busybox"
    command = [
      "tail"
    ]
    args = [
      "-f",
      "/dev/null"
    ]
    securityContext = {
      privileged : true
    }
    tty : true
    env = [
      {
        name  = "EXAMPLE"
        value = "VAR"
      }
    ]
  }

  restart_policy = "OnFailure"
}

Requirements

Terraform plugins

• Terraform >= 0.13.0
• terraform-provider-google plugin v1.8.0

Python Libraries

• terraform_external_data

Configure a Service Account

In order to execute this module you must have a Service Account with the following:

Permissions

• compute.disks.* on the project
• compute.diskTypes.get on the project
• compute.diskTypes.list on the project

Enable API's

In order to operate with the Service Account you must activate the following APIs on the project where the Service Account was created:

• Compute Engine API - compute.googleapis.com

Install

Terraform

Be sure you have the correct Terraform version (0.10.x), you can choose the binary here:

• https://releases.hashicorp.com/terraform/

File structure

The project has the following folders and files:

• /: root folder
• /examples: Examples for using this module
• /helpers: Scripts that the module invokes
• /test: Folders with files for testing the module (see Testing section of this file)
• /main.tf: main file for this module, contains all the resources to create
• /variables.tf: all the variables for the module
• /output.tf: the outputs of the module
• /readme.md: this file

Testing

Requirements

• docker
• terraform-docs 0.3.0

Autogeneration of documentation from .tf files

Run

make generate_docs

Integration test

Terraform integration tests

The integration tests for this module leverage kitchen-terraform and kitchen-inspec, and run entirely within docker containers.

The tests will do the following:

• Perform bundle install command
  • Installs kitchen-terraform and kitchen-inspec gems
• Perform kitchen create command
  • Performs a terraform init
• Perform kitchen converge command
  • Performs a terraform apply -auto-approve
• Perform kitchen validate command
  • Performs inspec tests.
    • Shell out to gcloud to validate expected resources in GCP.
    • Log into deployed resources to validate Docker configuration.
    • Make HTTP requests to endpoints that are expected to be online.
• Perform kitchen destroy command
  • Performs a terraform destroy -force

Before running integration tests, you need to configure terraform.tfvars for your particular environment editing test/fixtures/shared/terraform.tfvars to reflect your testing environment.

You can then use the following command to run the integration test in the root folder

make test_integration_docker

Linting

The makefile in this project will lint or sometimes just format any shell, Python, golang, Terraform. The linters will only be run if the makefile finds files with the appropriate file extension.

All of the linter checks are in the default make target, so you just have to run

make -s

The -s is for 'silent'. Successful output looks like below and exists with 0 exit code.

$ make -s
Running shellcheck
Running flake8
Running go fmt and go vet
Running terraform fmt
terraform fmt -diff -check=true -write=false .
terraform fmt -diff -check=true -write=false ./examples/instance_with_attached_disk
terraform fmt -diff -check=true -write=false ./examples/simple_instance
terraform fmt -diff -check=true -write=false ./modules/cos-coredns
terraform fmt -diff -check=true -write=false ./modules/cos-generic
terraform fmt -diff -check=true -write=false ./modules/cos-mysql
terraform fmt -diff -check=true -write=false ./test/fixtures/instance_with_attached_disk
terraform fmt -diff -check=true -write=false ./test/fixtures/shared
terraform fmt -diff -check=true -write=false ./test/fixtures/simple_instance
Running terraform validate
helpers/terraform_validate .

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.external: version = "~> 1.2"
* provider.google: version = "~> 2.12"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

helpers/terraform_validate ./examples/instance_with_attached_disk
Initializing modules...

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.external: version = "~> 1.2"
* provider.google: version = "~> 2.12"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

helpers/terraform_validate ./examples/simple_instance
Initializing modules...

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.external: version = "~> 1.2"
* provider.google: version = "~> 2.12"
* provider.random: version = "~> 2.2"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

helpers/terraform_validate ./modules/cos-coredns

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.google: version = "~> 2.12"
* provider.template: version = "~> 2.1"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

helpers/terraform_validate ./modules/cos-generic

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.google: version = "~> 2.12"
* provider.template: version = "~> 2.1"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

helpers/terraform_validate ./modules/cos-mysql

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.google: version = "~> 2.12"
* provider.random: version = "~> 2.2"
* provider.template: version = "~> 2.1"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

helpers/terraform_validate ./test/fixtures/instance_with_attached_disk
Initializing modules...

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.external: version = "~> 1.2"
* provider.google: version = "~> 2.12"
* provider.local: version = "~> 1.3"
* provider.random: version = "~> 2.2"
* provider.tls: version = "~> 2.0"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

helpers/terraform_validate ./test/fixtures/simple_instance
Initializing modules...

Initializing provider plugins...

The following providers do not have any version constraints in configuration,
so the latest version was installed.

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.external: version = "~> 1.2"
* provider.google: version = "~> 2.12"
* provider.random: version = "~> 2.2"

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.
Success! The configuration is valid.

Checking for required files LICENSE README.md
Testing the validity of the header check
..
----------------------------------------------------------------------
Ran 2 tests in 0.014s

OK
Checking file headers
Checking for trailing whitespace
Generating markdown docs with terraform-docs
Skipping ./test/fixtures/instance_with_attached_disk because README.md does not exist.
Skipping ./test/fixtures/shared because README.md does not exist.
Skipping ./test/fixtures/simple_instance because README.md does not exist.
$ echo $?
0

The linters are as follows:

• Shell - shellcheck. Can be found in homebrew
• Python - flake8. Can be installed with 'pip install flake8'
• Golang - gofmt. gofmt comes with the standard golang installation. golang is a compiled language so there is no standard linter.
• Terraform (built-in):
  • terraform fmt
  • terraform validate.
• File headers
• Trailing whitespaces

Known limitations

Managed instance group example is not migrated to Terraform 0.12. This is tracked as issue #28 Linters and integrations tests skip this example and associated tests for now.