Managing SC//Reliant Platform Manager data for containers
This page describes the properties in SC//Reliant™ Platform Manager that define your containers, the registries their images are pulled from, and their networking, volumes, and resource limits. For the container configurations the platform supports (singleton, clustered, or a mix of the two), see Managing containers. For a conceptual overview of volumes, see Using data volumes.
Understanding data priority
When the SC//Reliant Platform Manager stores data, the data for the cluster (the Cluster Docker Resources hash) takes precedence over singleton data (the Docker hash) for the same property. For example, when you are defining a Docker container network configuration, if you specify two networks with the same name (one on singleton and another on cluster) then when they are merged the one on the cluster will take precedence and be configured after Puppet is run.
The following is the priority order:
Cluster Docker ResourceshashDockerhash- Default property values
It's considered best practice to ensure that all containers have a unique name. When two containers have the same name, this causes unpredictable behavior on Docker DNS due to duplicate entries on Docker DNS redirecting to different containers. If you want to use similar names for different containers, the recommended approach is to use a suffix. For example, if you have two NGINX containers defined you may name them NGINX_fixed and NGINX_cluster.
Docker resources hash properties reference
The following are the high-level properties that are used when defining the resources for your containers. They are defined in the Docker and Cluster Docker Resources hashes in SC//Reliant Platform Manager. We dive deeper into each hash later in the document.
| Property | Type | Description | Required |
|---|---|---|---|
Proxy Server | Text | The proxy server address to use for pulling container images. | No |
Amazon Elastic Container Registry (ECR) | Hash | The configuration for the Amazon ECR private registry to pull container images from. This hash includes the URI of your Amazon ECR private registry as well as the AWS access key and AWS secret access key to authenticate to the registry to pull images. | No |
Microsoft Azure Container Registry (ACR) | Hash | The configuration for the ACR private registry to pull container images from. This hash includes the registry name, the service principal's application (client) ID, the service principal's password (client secret), and the Azure tenant ID. | No |
Google Artifact Registry (GCR) | Hash | The configuration for the GCR artifact registry to pull container images from. | No |
Other private registries | Hash | The general configuration for other Docker compatible registries to pull container images from. | No |
Docker networks | Hash | The Docker container network configuration. | Yes |
Volumes | Hash | The configuration details for data volumes. For containers inside the cluster, after defining a data volume, you should reference the volume in the Containers hash as shared volumes to bind mount them in a container. For containers outside the cluster, you should reference the volume in the Containers hash as attached volumes to bind mount them in a container. | No |
Containers | Hash | The Docker container configuration. A Shared Volumes hash is included to reference the shared volume to bind mount to the container. An Exclusive Volumes hash is included to configure a volume to bind mount to an individual container. | Yes |
Network Access Control | Hash | The network access control details. This is used to restrict external access to the containers to specific external networks. Using this option allows Docker to update iptables on the host. | No |
Docker Version | Text | The Docker Engine version to install on the node. | No |
Default Bridge IP Address | Text | The default bridge network address. | No |
Image Management | Hash | The container image management configuration. This includes configuring a schedule for pruning unused images and downloading images for staging. | No |
Container image management
The following hashes provide the configuration for the container image registry you use as well as any image management settings you'd like to apply to the nodes in your environment.
Amazon Elastic Container Registry (ECR) hash reference
When you use an Amazon ECR private registry to store your container images, you must enable the Amazon Elastic Container Registry (ECR) option in the Docker resources hash of your node group. This hash contains the AWS account and ECR private registry details used to authenticate and pull your container images. For more information, see What is Amazon Elastic Container Registry?.
| Field | Type | Description | Required |
|---|---|---|---|
| Registry URI | Text | The URI of your Amazon ECR private registry. It should be in the aws_account_id.dkr.region.amazonaws.com format where aws_account_id is your AWS account ID and region is the AWS Region your repositories reside in. | Yes |
AWS Access Key ID | Text | The AWS access key ID. This is used for authenticating to your private registry. | Yes |
AWS secret access key | Text | The AWS secret access key. This is used for authentication to your private registry. | Yes |
Microsoft Azure Container Registry (ACR) hash reference
When you use Microsoft Azure Container Registry to store your container images, you must enable the Microsoft Azure Container Registry (ACR) option in the Docker resources hash of your node group. This hash contains the ACR account and registry details used to authenticate and pull your container images. For more information, see Azure Container Registry authentication with service principals.
| Field | Type | Description | Required |
|---|---|---|---|
| Registry name | Text | The name of your Azure Container Registry. | Yes |
APP ID | Text | The service principal's application (client) ID. | Yes |
Password | Text | The service principal's password (client secret). | Yes |
Tenant | Text | The Microsoft Azure tenant ID. | Yes |
Google Artifact Registry (GCR) hash reference
When you use Google Artifact Registry to store your container images, you must enable the Google Artifact Registry (GCR) option in the Docker resources hash of your node group. This hash contains the GCR account and registry details to authenticate when pulling your container images. For more information, see Configure Docker authentication to Artifact Registry.
| Field | Type | Description | Required |
|---|---|---|---|
endpoint | Text | The endpoint of your Google Artifact Registry. It should be in the https://LOCATION-docker.pkg.dev format, where LOCATION is the regional or multi-regional location of the repository where the container image is stored. | Yes |
Client ID | Text | The Google Cloud service account client ID. This corresponds to the client_id value in your key file. | Yes |
Client Email | Text | The Google Cloud service account client email address. This corresponds to the client_email value in your key file. | Yes |
Private Key ID | Text | The Google Cloud service account key ID. This corresponds to the private_key_id value in your key file. | Yes |
Private Key | Text | The Google Cloud service account private key. This corresponds to the private_key value in your key file. | Yes |
Other private registries hash reference
When using another Docker-compliant private registry other than Docker Hub, Amazon ECR, Microsoft Azure Container Registry, or Google Artifact Registry, you must enable the Other private registries option in the Docker resource hash to provide the registry details.
If you use a public registry that doesn't require authentication, no additional details are needed in SC//Reliant Platform Manager for that public registry. You can simply reference the repository details when defining your container.
| Property | Type | Description | Required |
|---|---|---|---|
| Registry URL | Text | The URL or URI of the Docker compatible registry. | Yes |
Username | Text | The username to use when authenticating to the registry. | Yes |
Password | Text | The password to use when authenticating to the registry. | Yes |
Email Address | Text | The email address associated with the registry. | No |
Version | Text | The version number of the registry. | No |
Image management hash reference
You can configure SC//Reliant Platform Manager to perform management tasks on the container images on your nodes. These tasks include configuring a schedule for pruning unused images and downloading images for staging. On each host that is running containers, you can view the /opt/reliant/managed_images file for a list of Docker images managed by the SC//Reliant platform.
| Property | Type | Description | Required |
|---|---|---|---|
Prune Images | Hash | Allows you to define a cronjob that prunes unused Docker images on a schedule. | No |
Stage Images | Hash | Allows you to define a cronjob that pulls a list of container images on a schedule. This is useful for pre-staging Docker container images. Any images defined here are placed into a managed file which is excluded from pruning. | No |
Docker networking
Docker networks hash reference
The Docker networks hash is used to define the networking configuration the containers you create can use. Once a network is defined, you can connect a container to the network in the Containers hash.
Docker doesn't support updating the configuration of a network after it's been created on a host. If you need to change a network configuration, you must disconnect all containers from the network, remove the network, and then recreate the network using SC//Reliant Platform Manager and Puppet.
| Property | Type | Description | Required | Default value |
|---|---|---|---|---|
| Network name | Text | The name of the network to be created. | Yes | - |
Driver | Text | The Docker network driver to use. The most common drivers to use are bridge, host, or none. For more information, see Docker network drivers. | Yes | bridge |
Network Driver Options | Text | The list of network driver options to use. The available options are dependent on the network driver used. For more information, see Docker network drivers. When a driver option is specified, it must be in the format <option>=<value>. | No | - |
Subnet | Multi | The IP address subnet to assign to the network. It can be specified as either a CIDR or you can specify DHCP. | No | - |
Gateway | Text | The IP address of the gateway for the Docker network subnet. | No | - |
IP address range for DHCP | Text | When DHCP is specified for the subnet, this is the IP address range for the Docker network. | No | - |
Network Access hash reference
| Property | Type | Description | Required | Default value |
|---|---|---|---|---|
| Network access name | Text | The network access rule name | Yes | - |
Source Network | Text, IP Address, or DHCP | Source network address that will be allowed to access Docker containers. The address can be either a network IP address (with /mask), or a plain IP address. Ex: 192.168.0.0/24 | Yes | - |
Protocol | Text | The protocol of the rule or of the packet to check. The specified protocol can be one of tcp, udp, icmp, or the special keyword all. | No | all |
Destination Docker Network Name | Text | The name of the Docker network to which the container is connected. External access is limited to containers on this network. The network name can be a name of a network created on the Networks sub-hash or empty. If no network name is given, all Docker containers will be accessible from this source network. | No | - |
Data volumes
The following hashes are used to manage the data volumes associated with your containers.
Volumes hash reference
The Volumes hash is where you define all of the data volumes your containers need to use. These data volumes are then referenced in the Containers hash for each container that needs to use them. The data volumes are created on the node and then bind mounted in the configured container. For a deeper dive on how data volumes are used, see Using data volumes.
| Property | Type | Description | Required | Default value |
|---|---|---|---|---|
Host Path | Text | The absolute path on the host to bind mount the shared volume to. | No | /docker/<shared_mount_name> is the default if no value is specified or if DRBD is configured. |
DRBD | Hash | The configuration for DRBD. This is an open source distributed block storage solution that is used to replicate volumes across clustered nodes. | No | - |
Port | Number | The TCP network port that DRBD uses to facilitate replication and synchronization between the nodes in the cluster. | Yes, if DRBD is configured. | - |
Device Name | Text | The virtual block device name that DRBD creates and manages on each node in the cluster. The Device Name value must be unique. We recommend using sequential values like drbd90, drbd91, etc. Keep in mind that if you are also hosting KVM virtual machines that are configured for DRBD replication that the device names must also be unique across both technologies. | Yes, if DRBD is configured. | - |
Volume Group | Text | The Logical Volume Management (LVM) volume group that DRBD utilizes as the underlying storage for replication. | Yes, if DRBD is configured. | - |
Disk Size | Text | The size of the DRBD managed block device. You should ensure that the hard drive on each host node has enough space for the sum of all of the DRBD virtual block devices you define in SC//Reliant Platform Manager. It's recommended that you specify the unit postfix. | Yes, if DRBD is configured. | - |
User | Text | The user that is set as the owner of the mapped directory for the shared volume. | No | If no value is set, a user named shared-mount is used. |
Group | Text | The group that is set as the owner of the mapped directory for the shared volume. | No | If no value is set, a group named shared-mount is used. |
Shared Volumes hash reference
The Shared Volumes hash is defined inside the Containers hash inside of the Cluster Docker Resources hash. This is used when you have a data volume that is intended to be shared by multiple containers.
| Property | Type | Description | Required | Default value |
|---|---|---|---|---|
Container Path | Text | The absolute path inside the container to bind the mount to. | Yes | - |
Exclusive Volumes hash reference
The Exclusive Volumes hash is defined inside the Containers hash inside of the Cluster Docker Resources hash. This is used when you have a data volume that is intended for use only by a single container.
| Property | Type | Description | Required | Default value |
|---|---|---|---|---|
Container Path | Text | The absolute path inside the container to bind the mount to. | Yes | - |
Host Path | Text | The absolute path on the host to bind to the container. | No | /docker/container_name-mount_name is the default if no value is specified or if DRBD is configured. |
DRBD | Hash | The configuration for DRBD. This is an open source distributed block storage solution that SC//Reliant uses. | No | - |
Port | Number | The port to use for the drbd service on the cluster. | Yes, if DRBD is configured. | - |
Device | Text | The DRBD device name. | Yes, if DRBD is configured. | - |
Volume Group | Text | The LVM volume group to use to make the DRBD logical volume. | Yes, if DRBD is configured. | - |
Disk Size | Text | The size of the DRBD disk. It's recommended that you specify the unit postfix. | Yes, if DRBD is configured. | - |
Container resource definitions
Resource Limitations hash reference
The Resource Limitations hash is where you define the host node resources (CPU and memory) to make available to the containers running on the host node.
| Property | Type | Description | Required | Default value |
|---|---|---|---|---|
Memory | Text | The maximum amount of memory to allocate to the container. | Yes | - |
Swap Memory | Text | The amount of memory the container is able to swap to disk. | Yes | - |
CPU Resources | Text | The maximum amount of CPUs to allocate to the container | Yes | - |
CPU Shares | Number | Set this property to a value greater or less than the default of 1024 to increase or reduce the container’s weight, and give it access to a greater or lesser proportion of the host machine’s CPU cycles. This is only enforced when CPU cycles are constrained. When plenty of CPU cycles are available, all containers use as much CPU as they need. | Yes | 1024 |
Container definitions
Containers hash reference
The Containers hash is where you define the Docker containers to run in your environment.
When specifying environment variables, if the environment variable value includes special characters or spaces then we recommend using the Environment File Content parameter as opposed to the Environment Variables parameter. This is due to a limitation of the Docker Resource agent which can't properly interpret arguments that have spaces in them.
| Property | Type | Description | Required | Default value |
|---|---|---|---|---|
| Container name | Text | The name of the container. | Yes | - |
Image | Text | The container image name. If no registry details are provided, an image on Docker Hub is assumed. If you are using another registry, you should specify the full registry URI including the repository name. | Yes | - |
Tag | Text | The tag to use for the container image. | No | - |
Force Image Update | Boolean | Whether or not to force the image to be updated for the container. This option assumes the tag already exists but has a different digest than the existing container image. | No | Disabled |
User | Text | The user (UID) to run the container as. For example, admin. | No | - |
Group | Text | The group (GID) to run the container as. | No | - |
Exposed Ports | Text | The ports to expose outside of the defined Docker network. | No | - |
Networks | Text | The name of the Docker network the container uses. This is defined in the Custom Networks hash. | Yes | - |
Shared Volumes | Hash | The shared volume(s) to mount inside the container. The shared volume must first be defined in the Shared Volume(s) hash prior to being available to specify here. | No | - |
Path | Text | The file path to mount the shared volume to inside the container. This is only specified when the Shared Volumes hash inside the Containers hash is enabled. | No | - |
Exclusive Volumes | Hash | The details of the volumes to mount inside the container. These are separate from the shared volumes. | No | - |
Depends On | Text | The dependencies defined for container startup. If you provide a container name, that container must start up before this container is able to. | No | - |
Environment File Content | Text | The environment variables to pass to the container. These must be specified one environment variable per line. They are then converted into an environment variable file that is passed to the container. This value maps to the --env-file option on the docker run command. | No | - |
Environment Variables | Text | The environment variables to pass to the container. These are specified as individual variables. This value maps to Env in the docker create-container command and the --env option on the docker run command. | No | - |
Resource Limitations | Hash | The CPU and memory resource allocations to reserve for the container. | No | - |
Optional Runtime Parameters | List | A list of Docker runtime parameters. These are specified as key-value pairs and give you additional control over the capabilities available to the container. For more information, see Runtime privilege and Linux capabilities in the Docker documentation. |
Environment File Content and Environment Variables
There are two ways to inject environment variables into a container at runtime. You can specify individual environment variables by using the Environment Variables property or you can specify multiple environment variables by having the SC//Reliant platform create an environment variable file by specifying a line delimited list of environment files using the Environment File Content property.
One of the unique features within the SC//Reliant Platform Manager is the ability to specify a property reference in an environment variable. For example, if you had a property named Docker Release Tag and you wanted to reference that property value as an environment variable, you could use the following syntax when specifying the environment variable. This feature only works with the Environment Variables property.
TEST_ENV=%{lookup('my_docker_release_tag')}For an example of using a property reference to set a container's image tag on each node, see Use case: Specifying container image tags as a property reference.