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.2"

  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

Name	Description	Type	Default	Required
container	A description of the container to deploy	any	{ "command": "ls", "image": "gcr.io/google-containers/busybox" }	no
cos_image_family	The COS image family to use (eg: stable, beta, or dev)	string	"stable"	no
cos_image_name	Name of a specific COS image to use instead of the latest cos family image	string	null	no
cos_project	COS project where the image is located	string	"cos-cloud"	no
restart_policy	The restart policy for a Docker container. Defaults to OnFailure	string	"OnFailure"	no
volumes	A set of Docker Volumes to configure	any	[]	no

Outputs

Name	Description
container	The container definition provided
container_vm	The complete container VM image object to use for the GCE instance
metadata_key	The key to assign metadata_value to, so container information is attached to the instance
metadata_value	The generated container configuration
restart_policy	The restart policy provided
source_image	The self_link to the COS image to use for the GCE instance. Equivalent to container_vm.self_link
vm_container_label	The COS version to deploy to the instance. To be used as the value for the vm_container_label_key label key. Equivalent to container_vm.name
vm_container_label_key	The label key for the COS version deployed to the instance
volumes	The volume definition provided

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.