Skip to main content

Applications

Add environment variables to a container​

To set environment variables for a container use the env section in the application specification. For example, to set environment variables USERNAME and LOG_LEVEL on a container:

name: theater-room-manager
services:
  - name: theater-operations
    containers:
      - name: digital-assets-manager
        env:
          USERNAME: my-user
          LOG_LEVEL: debug

Add configuration files to a container​

You can create a configuration file that is mounted into your container with the contents of the file inlined in your application specification. For example, if you would like to start the container consume-config with a configuration file in /config.txt then your application specification should contain:

name: with-config-file
services:
  - name: consume-config
    containers:
      - name: consume-config
        mounts:
          - volume-name: config-volume
            files:
              - name: my-config
                mount-path: /config.txt
    volumes:
      - name: config-volume
        config-map:
          items:
            - name: my-config
              data: |
                username: my-user
                password: my-secret-password

When the consume-config container starts, the file /config.txt will contain:

username: my-user
password: my-secret-password

Add ephemeral volume configuration to a service​

Request disk space allocated per service instance that may be used by one or shared by multiple containers within the service. The data in such volume persists as long as the service is scheduled on a particular host.

name: with-ephemeral-volume
services:
  - name: cache-on-disk
    containers:
      - name: cache-on-disk
        mounts:
          - volume-name: cache-volume
            mount-path: /cache
    volumes:
      - name: cache-volume
        ephemeral-volume:
          size: 10GB

Add persistent volume configuration to a service​

Request disk space allocated per service instance that may be used by one or shared by multiple containers within the service. The data in such volume persists even after the application is removed from the site, until the volume is manually removed.

name: with-persistent-volume
services:
  - name: persistent-storage
    containers:
      - name: persistent-storage
        mounts:
          - volume-name: storage
            mount-path: /storage
    volumes:
      - name: storage
        persistent-volume:
          size: 10GB

Limiting container layer size​

Container writable layer can be limited using the following configuration. This has no effect on the underlying image size, which is read-only from container's perspective.

name: with-container-layer-limit
services:
  - name: some-service
    containers:
      - name: container-one
        container-layer-size: 1GiB

Add ingress IP configuration to a service​

You have a service that needs to export tcp ports 80 and 8080 and udp port 90 to the local network, with connections only allowed from 192.0.2.0/24 IP range.

name: with-ingress
services:
  - name: need-ingress
    network:
      ingress-ip-per-instance:
        inbound-access:
          rules:
            192.0.2.0/24: allow
        protocols:
          - name: tcp
            port-ranges: "80,8080"
          - name: udp
            port-ranges: "90"

Advanced ingress IP configuration​

The same scenario as above, but select a specific network interface to allocate ingress address on. In addition to that, on sites with ingress addresses allocated from pool (ingress-allocation-method: pool) allocate an IP address from a range that has a specific label value.

note

While site provider has access to all ingress address ranges, its subtenants are limited to ranges with no assigned labels by default. Site provider may grant a subtenant access to ingress address ranges using resource-profiles .

Both network interface labels and ingress address range labels are configured by the site provider.

name: with-ingress
services:
  - name: need-ingress
    network:
      ingress-ip-per-instance:
        inbound-access:
          rules:
            192.0.2.0/24: allow
        protocols:
          - name: tcp
            port-ranges: "80,8080"
          - name: udp
            port-ranges: "90"
        match-interface-labels: type = wan
        match-ipv4-range-labels: scope = global

Map ingress port to a different port inside the service​

If it is desirable to redirect an ingress port to a different port inside the container, then an init-container may be used to configure the firewall instance inside the service's network namespace to perform the redirection.

Note that the tenant must be allowed to request an additional net-admin container capability in order to be able to configure the firewall, which requires a container-net-admin policy capability. See Grant capabilities to subtenant for detailed instructions on how to do ensure the tenant has the necessary privileges.

The following application specification snippet provides an example on how to map ingress TCP port 80 to port 8000 inside the service.

name: ingress-port-map
services:
  - name: port-map
    network:
      ingress-ip-per-instance:
        protocols:
          - name: tcp
            port-ranges: "80"
    init-containers:
      - name: port-map
        image: registry.gitlab.com/avassa-public/application-examples/nftables:1.0
        additional-capabilities:
          - net-admin
        cmd:
          - nft
          - |
            table ip port-map {
              chain port-map {
                type nat hook prerouting priority dstnat; policy accept;
                tcp dport 80 redirect to :8000
              }
            }
    containers:
      ...

Allow unrestricted outbound network access for a service​

You have a service that needs to open connections to external networks.

Incoming connections on ingress address (if any) and communication with other services on the same application network are excluded from the outbound access limitations.

name: with-outbound
services:
  - name: need-outbound
    network:
      outbound-access:
        allow-all: true

Allow restricted outbound network access for a service​

You have a service that needs to open connections to IP addresses within specific external networks, so the outbound network access should be limited to these networks.

Incoming connections on ingress address (if any) and communication with other services on the same application network are excluded from the outbound access limitations.

name: limited-outbound
services:
  - name: need-outbound
    network:
      outbound-access:
        rules:
          192.0.2.0/24: allow
          203.0.113.0/24: allow
          203.0.113.64/26: deny
          203.0.113.100/32: allow

You have a service that needs to open connections to external IP addresses anywhere but specific networks that should be blocked. Just like in the previous example, these limitations do not affect inbound connections or communication on the application private network.

name: limited-outbound
services:
  - name: need-outbound
    network:
      outbound-access:
        default-action: allow
        rules:
          192.0.2.0/24: deny

Host network mode / attaching to host's default network namespace​

This functionality must be used with extreme care, please read the fundamentals section on attaching to host's default network namespace before proceeding.

In order to get access to this functionality the tenant must be granted service-host-network-mode capability by the system provider as explained in the policy how-to.

An application's service may be requested to be attached to the host's default network namespace as follows:

name: host-network-mode
services:
  - name: attached-to-host-network
    network:
      host: true

Add strongbox secrets to an application​

First add a strongbox vaults named operations with a key value map named credentials.

name: credentials
allow-image-access:
  - "*"
data:
  username: my-username
  password: my-secret-password

Then create an application to access the secrets.

name: theater-room-manager
services:
  - name: theater-operations
    variables:
      - name: OPERATIONS_USERNAME
        value-from-vault-secret:
          vault: operations
          secret: credentials
          key: username
    containers:
      - name: digital-assets-manager
        image: "avassa-public/avassa-public/movie-theaters-demo/digital-assets-manager"
        env:
          USERNAME: ${OPERATIONS_USERNAME}
        mounts:
          - volume-name: credentials
            mount-path: /credentials
    volumes:
      - name: credentials
        vault-secret-ref:
          vault: operations
          secret: credentials
    mode: replicated
    replicas: 1

The system will assign the environment variable USERNAME the value my-username (see lines 5-9 and line 14).

The system will also create a directory /credentials (see lines 15-22). In this directory the system will mount the values from the key value map as files, i.e. there will be two files:

  • /credentials/username, containing the string my-username.
  • /credentials/password, containing the string my-secret-password.
tip

To distribute a unique secret to each site, see here.

Add replication to a service​

You have a service that needs to run in three replicas per site

name: theater-room-manager
services:
  - name: theater-operations
    mode: replicated
    replicas: 3

Control host placement​

You have a service that needs to run on hosts with a certain label, access-control: true.

name: theater-room-manager
services:
  - name: theater-operations
    mode: replicated
    replicas: 1
    placement:
      match-host-labels:
        access-control = true

Request GPU passthrough​

This instruction explains how to enable your application to access the GPU.

note

Refer to the GPU passthrough tutorial to understand the prerequisites to be able to request GPU passthrough in the application specification.

name: sample-gpu-app
version: 0.0.2
services:
  - name: s
    mode: replicated
    replicas: 1
    containers:
      - name: c
        image: nvcr.io/nvidia/k8s/cuda-sample:vectoradd-cuda10.2
        entrypoint:
          - /bin/bash
        cmd:
          - "-c"
          - sleep infinity
        gpu:
          labels:
            - all
          nvidia-patterns:
            - memory >= "4 GiB", driver-version > "515", display-mode == "Enabled"
          number-gpus: 1
          nvidia-driver-capabilities: utility, graphics, display

The parameters in the gpu configuration section in the example above:

  • labels contains references to gpu-labels. The labels are defined by the site provider and the application owner must have access to them
  • nvidia-patterns is an optional parameter to further refine the set of GPUs to be passed through using a match expression
  • number-gpus is an optional parameter to indicate the exact number of GPUs to be passed through
  • nvidia-driver-capabilities is an optional parameter to control the libraries and binaries mounted into the container by the NVIDIA runtime