Skip to main content


Contexts provide a means to share common configuration between Configurations. The resource type is Cluster scoped and can be used by any Configuration in the cluster.


This feature is only available from v0.3.25 onwards

Create a Context

You can create a Context like so.

kind: Context
name: default
## All variables MUST follow the pattern of 'description' and 'value'. The
## value can be any complex or simple type (boolean, int, map, object etc)
# Is the name of the variable
# Provides a description to the consumer of the input
description: Is the network identifier we are residing
# The value of the value
value: vpc-1223133113
# Provides a description to the consumer of the input
description: |
Is a collection of subnet id's which are publicly available i.e.
they are attached to an internet gateway
# The value of the value
- subnet-12312312312
- subnet-32332321312

The resource contains a map of variables; note each variable MUST have a description and value, with the value being any simple (integer, boolean, string) or complex type (maps, list, maps or maps and so forth).

Configure Preloading


Currently the cloud which has support for automatic preloading is AWS. Other providers are on the roadmap, but they have not been implemented yet.

Terranetes has the ability to populate a Context automatically; retrieving details about the cluster the controller resides and populating them into a Context. Currently this feature is limited to AWS only.

In order to use the feature we need to update the configuration of a Provider; It is the Providers credentials which the preloading will use to retrieve the information from the cloud vendor.

kind: Provider
name: aws
# Source and be 'secret' or 'injected'. When using a 'secret' you
# must specify the spec.secretRef which defines the name of the
# secret in the controller namespace containing the credentials.
source: secret
# Provider can be google, aws, azurerm, alicloud, azurestack, googleworkspace etc
provider: aws
# Provides configuration for the contextual data preloader (currently only
# available for aws)
# Indicates if the preloading should be enabled
enabled: true
# Is the EKS cluster we use to pivot network and settings around
cluster: eks
# Is the cloud region the cluster above resides
region: eu-west-2
# Is the terranetes context resource we should provision
context: default
# Used when spec.source is secret.
namespace: terraform-system
name: aws

The spec.preload in the Provider needs the following information.

  • enabled Indicates if we should preload any data into a Context.
  • cluster Is the cloud name of the cluster we reside in i.e. the EKS cluster name.
  • region Is the cloud region the cluster (spec.preload.cluster) resides in.
  • context Is the name of the Context you wish to populate the values into.

Once this information has been defined, a Context resource be automatically provisioned and preloaded with details, as such;

$ k get default  -o yaml
kind: Context
generation: 1
labels: aws
name: default
description: AWS ARN for the Kubernetes cluster
value: arn:aws:eks:eu-west-2:XXXXXXXXX:cluster/eks-test
description: The security group ID attached to the EKS cluster
value: sg-XXXXXXXXX
description: The endpoint for the EKS cluster
description: The name of the EKS cluster
value: eks
description: The platform version of the EKS cluster
value: eks.6
description: Indicates whether or not the EKS cluster has private access enabled
value: true
description: Indicates whether or not the EKS cluster has public access enabled
value: false
description: The CIDR blocks that are allowed access to the EKS cluster
description: The ARN of the IAM role that provides permissions for the EKS cluster
value: arn:aws:iam::XXXXXXXXXX:role/eks-test-role
description: A list of all route tables id associate to the subnets which are
part of the EKS cluster
- rtb-04dbff51b83821XXX
description: The ID of the VPC used by the EKS cluster
value: vpc-0a6f4fbb4bXXXXXXX

How to reference a Context

Contexts can be referenced from any Configuration like so

kind: Configuration
name: bucket
name: aws
- context: default
key: vpc_id
name: vpc_id

The spec.valueFrom requires the Context name, the key is the name of the variable in the context and the name is the variable you need to present this as to the terraform module. The optional field simply means both the context and any value reference, if they don't exist, can continue without failure. By default, anything missing (context or value) will defer the Configuration until they are present.

Using a Custom Preload

Terranetes comes prebuilt with a loader to extract details from the cloud vendor, but perhaps it doesn't contain the details you need. You can solve this in two ways

a) Configuration can reference multiple Context resources, so you can provision with additional details / values. b) Override the preload image in the controller and run your own custom loader.

The first one is simple and can achieved in multiple ways; manually, ci, helm and so forth. The second option, overloading the controller's preload images requires you update the --preload-image argument. In the helm chart, this can be done via

preload: IMAGE:TAG

Note, the entrypoint when using this image is currently hardcoded, so you have to ensure in the image we have an executable at /bin/preload. The following arguments will also be passed, via environment variables to the execution

  • CLOUD is the cloud vendor designation from the Provider the preload is configured on i.e. spec.provider.
  • CLUSTER is the cluster name from the preload configuration i.e spec.preload.cluster.
  • CONTEXT is the name of the context (spec.preload.context) defined in the Provider configuration.
  • PROVIDER is the name of the provider the preload was configured on on the Provider resource.
  • REGION is the cloud region configured in the Provider preload configuration i.e spec.preload.region.

When using a custom loader the executable is responsible for two things

  • Retrieving the cloud details and constructing a valid Context resource.
  • Creating or updating the CONTEXT in the Kubernetes cluster itself.

The controller is responsible for ensuring execution occurs, handing jobs fails and configuring the job with Provider credentials.