About Template Functions and Arguments

Template functions enable you to programmatically access and update details about service and stack deployments managed by Oracle Container Cloud Service. Template arguments expose a deployment’s properties so that you can manipulate them using template functions.

You can incorporate Oracle Container Cloud Service template functions and arguments into service and stack definitions using the Container Console’s Service Editor and Advanced (YAML) Stack Editor to programmatically get and set values for configuration options and environment variables.

Typically, template functions and arguments return values from:

  • the Key/Value store in Oracle Container Cloud Service’s Service Discovery database

  • Oracle Container Cloud Service environment variables (with names starting ‘OCCS_’) related to the deployment

One way to use template functions and arguments is to call them to set environment variables in a running container's host. Application code in the container can then use those environment variables.

You’ll also find template functions and arguments particularly useful when you want to create generic services and stacks that can be reused to meet different requirements. For example, you might want to define a stack to deploy a blogging application that comprises WordPress and a mariadb database. If you only have one such blogging application to deploy, you can create a stack definition that explicitly specifies the Docker images to run as Docker containers for the application, the host ports to use when the application is deployed, and the database root password.

Such a stack definition is shown below:

# https://hub.docker.com/_/wordpress/
# Example docker-compose.yml for wordpress:
# Run docker-compose up, wait for it to initialize completely,
# and visit http://localhost:8080 or http://host-ip:8080.
wordpress:
  image: wordpress:latest
  ports:
    - 8080:80
  links:
    - db:mysql

db:
  container_name: db
  image: mariadb:latest
  environment:
    - MYSQL_ROOT_PASSWORD=Eric-Password

So far, so good. But if you have ten similar blogging applications to deploy, creating and maintaining a separate stack definition for each application could quickly become tiresome.

By incorporating template functions in a stack definition, you can reuse the same stack definition to deploy multiple different applications. In the case of deploying the ten different blogging applications, you could incorporate template functions into a single stack definition to interrogate the Key/Value store in the Oracle Container Cloud Service Service Discovery database and return the port and the database root password to use for each blogging application, as well as the name and location of each application’s data partition mount point.

Such a stack definition is shown below:

# https://hub.docker.com/_/worddivss/
# Example docker-compose.yml for wordpress:
# Run docker-compose up, wait for it to initialize completely,
# and visit http://localhost:8080 or http://host-ip:8080.
wordpress:
  image: wordpress:latest
  ports:
    - {{kv_get .EnvironmentID .StackID .ServiceID "port"}}:80
  links:
    - db:mysql

db: # ensure db sorts before wordpress
  container_name: db
  image: mariadb:latest
  environment:
    - MYSQL_ROOT_PASSWORD={{kv_get {{.ServiceID}} "pass" }}
  volumes:
    - /NFS/{{.EnvironmentID}}/{{.DeploymentID}}/{{.ServiceID}}/{{.ServiceSlot}}:/mnt/data