Substitution (dynamic templates)
Substitution provides a powerful mechanism to dynamically transform application configuration that is tailored for each device.

Substitution

Synpse provides the ability to expand, or substitute, application and device metadata to facilitate dynamic application configurations.

Available Environment Variables

  • Device environment variables (defined by user)
  • Synpse environment variables (automatically set, reference here)

Dynamic Application Spec

Most of the values in the application spec can be changed, for example:
  • Container name
  • Image name (you can adapt image name based on architecture)
  • Environment variables
  • Secrets
  • Volumes
Application name, scheduling configuration or the yaml structure itself cannot be changed as it will prevent yaml from being correctly marshalled.

Example Image Based On CPU Arch

If you have an application that is deployed on multiple devices of various CPU architectures (amd64, arm, arm64), you can specify image substitution (see available environment variables):
1
name: example-app
2
scheduling:
3
type: AllDevices
4
spec:
5
containers:
6
- name: my-app
7
image: docker.io/my-org/my-app-${SYNPSE_DEVICE_ARCH}:latest
Copied!
On a regular amd64 (x86) machine it will be:
1
name: example-app
2
scheduling:
3
type: AllDevices
4
spec:
5
containers:
6
- name: my-app
7
image: docker.io/my-org/my-app-amd64:latest
Copied!
While on a 32-bit arm machine the spec will become:
1
name: example-app
2
scheduling:
3
type: AllDevices
4
spec:
5
containers:
6
- name: my-app
7
image: docker.io/my-org/my-app-arm:latest
Copied!

Example Device Env Substitution

Let's say you have set an environment variable on the device called:
1
REGION=sillicon-valley
Copied!
Now, you can use that environment variable to create something else, for example a URL on which the device will be accessible by users (assuming you have configured domain, etc.):
1
name: example-app
2
scheduling:
3
type: AllDevices
4
spec:
5
containers:
6
- name: my-app
7
image: docker.io/my-org/my-app:latest
8
env:
9
- name: PUBLIC_ADDRESS
10
value: https://${REGION}.example.com
Copied!
And your application will then see an environment variable which equals
1
PUBLIC_ADDRESS=https://sillicon-valley.example.com
Copied!

String Operations

Synpse provides partial emulation for bash string operations. This can be used to manipulate string values prior to substitution.
  • Example variable substitution with substring:
1
name: example-app
2
scheduling:
3
type: AllDevices
4
spec:
5
containers:
6
- name: my-app
7
image: docker.io/my-org/my-app:latest
8
env:
9
- name: CUSTOMER
10
value: ${CUSTOMER_ID:0:4} # Getting first 4 symbols
Copied!
Synpse emulates the below string operations:
1
${parameter^}
2
${parameter^^}
3
${parameter,}
4
${parameter,,}
5
${parameter:position}
6
${parameter:position:length}
7
${parameter#substring}
8
${parameter##substring}
9
${parameter%substring}
10
${parameter%%substring}
11
${parameter/substring/replacement}
12
${parameter//substring/replacement}
13
${parameter/#substring/replacement}
14
${parameter/%substring/replacement}
15
${#parameter}
16
${parameter=default}
17
${parameter:=default}
18
${parameter:-default}
Copied!
Synpse makes a best-effort to emulate these operations however we do not promise perfect emulation.

Escaping

If you do not want the system to evaluate an expression it must be escaped:
1
name: example-app
2
scheduling:
3
type: AllDevices
4
spec:
5
containers:
6
- name: my-app
7
image: docker.io/my-org/my-app:latest
8
env:
9
- name: DEVICE_NAME
10
value: ${MY_DEVICE_NAME}
Copied!

Caveats

If your environment variable contains *, it will be automatically quoted to avoid parsing issues. For example:
1
env:
2
- name: MY_DOMAIN
3
value: ${MY_DOMAIN}
Copied!
Where MY_DOMAIN=*.example.com will be rendered as:
1
env:
2
- name: MY_DOMAIN
3
value: *.example.com
Copied!
However, the following example
1
env:
2
- name: MY_DOMAIN
3
value: https://${MY_DOMAIN}
Copied!
Will be rendered as:
1
env:
2
- name: MY_DOMAIN
3
value: https://"*.example.com"
Copied!
Which can lead to issues in your applications. In these scenarios, try to avoid using environment variable substitution.
Last modified 1mo ago