Template

This generates the outputs of a Driver based on Go templates. This is very similar to the templates used in Helm. You can use almost all the features as you would in Helm.

The Driver can be used to produce manifests, resource outputs and manipulate the Driver cookie. The Driver is a “Universal Driver” which means it can be used for all resource types.

Property Description
Resource type Any
Account type None

Inputs

Values

Name Type Description
templates object Contains objects that will be evaluated as templates.

Template objects

Each object in the template will be evaluated using the same evaluation algorithm. All objects are optional.

Object Type Description
init any Must evaluate to any valid YAML. The init object is evaluated first and then made available as .init to other objects.
cookie any Must evaluate to any valid YAML. The result of evaluating this object is stored as a cookie. This will be available on subsequent requests as .cookie.
manifests object Must evaluate to a map of ManifestLocation objects. These will be transformed and returned as the manifest property in the Driver outputs.
outputs object Must evaluate to an object. Properties to be available on resource.values in the output.

Manifest Location objects

Each manifest location object must have 2 properties: location and data.

The location field must have one of the following types

Location Schema Notes
containers Container This should be a valid Kubernetes Container object.
volumes Volume This should be a valid Kubernetes Volume object.
namespace Any The manifest will be injected into the deployment namespace. If the namespace property in the Metadata section should not be included the resource will be placed in that namespace.
cluster Any Intended for cluster level resources.

The data object must evaluate to a valid Kubernetes manifest as raw YAML. (i.e. not a string containing YAML.)

Secrets

Name Type Description
templates object Contains objects that will be evaluated as templates.

Template objects

Each object in the template will be evaluated using the same evaluation algorithm. All objects are optional.

Object Type Description
outputs object Must evaluate to an object. Properties to be available on resource.secrets in the output.

Notes

Creating templates

The jq utility can be used to quickly convert an input into a JSON encoded string:

cat template.yaml | jq -sR

Using the init template object

The init template object is a useful way to do things like generate common data that is needed across templates. For example, a common usecase is the need to generate a random ID to return from the Driver. The ID should be stored as a cookie so that the same ID can be returned in future.

Here is an example set of template objects that could do this:

templates:
  init:
    randomId: |
      {{- if and .cookie .cookie.randomId }}
        {{- .cookie.randomId }}
      {{- else }}
        {{- randAlphaNum 16 }}
      {{- end }}
  cookie:
    randomId: {{ .init.randomId }}
  outputs:
    randomId: {{ .init.randomId }}

This example will generate a random ID the first time it is called and return the same ID on all subsequent calls.

Examples

See the Template Driver examples page for a collection of examples.

Here is an example of using the template Driver generate an Ingress manifest. This can be used as a drop in replacement for the humanitec/ingress Driver as long as there is no more than one ingress configured per environment.

Set the following environment variables for the CLI and API commands:

Variable Example Description
HUMANITEC_TOKEN my-token The authentication token for accessing the Humanitec API.
HUMANITEC_ORG my-org-id The unique identifier for the organization in Humanitec.

Use the command below for the interface of your choice.

  1. Create a file defining the Resource Definition you want to create:
cat << EOF > template-ingress.yaml
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: template-ingress
entity:
  name: Template Ingress
  type: ingress
  driver_type: humanitec/template
  driver_inputs:
    values:
      templates:
        manifests:
          ingress:
            location: namespace
            data: |
              apiVersion: networking.k8s.io/v1
              kind: Ingress
              metadata:
                name: template-ingress
              spec:
                rules:
                - host: {{ .resource.host }}
                  http:
                    paths:
                    {{- range $path, $param := .resource.rules.http }}
                    - backend:
                        serviceName: {{ $param.name }}
                        servicePort: {{ $param.port }}
                      pathType: ImplementationSpecific
                    {{- end }}
                tls:
                - hosts:
                  - {{ .resource.host }}
                  secretName: {{ .resource.tls_secret_name }}
  criteria:
  - env_type: test-envs
EOF
  1. Use the humctl create command to create the Resource Definition in the Organization defined by your configured context:
humctl create -f template-ingress.yaml
rm template-ingress.yaml

Expected output:

id              type    driver_type             driver_account
cookie-config   config  humanitec/template      -

Note that the data in the manifest is provided as a JSON encoded string which will evaluated as a template to a raw YAML object.

curl https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/defs \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary '{
  "id": "template-ingress",
  "name": "Template Ingress",
  "type": "ingress",
  "driver_type": "humanitec/template",
  "driver_inputs": {
    "values": {
      "templates": {
        "manifests": {
          "ingress": {
            "location": "namespace",
            "data": "apiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n  name: template-ingress\nspec:\n  rules:\n  - host: {{ .resource.host }}\n    http:\n      paths:\n      {{- range $path, $param := .resource.rules.http }}\n      - backend:\n          serviceName: {{ $param.name }}\n          servicePort: {{ $param.port }}\n        pathType: ImplementationSpecific\n      {{- end }}\n  tls:\n  - hosts:\n    - {{ .resource.host }}\n    secretName: {{ .resource.tls_secret_name }}\n"
          }
        }
      }
    }
  },
  "criteria": [
    {"env_type":"test-envs"}
  ]
}'
Top