Docker Proxy Configuration

StarlingX uses publicly available container runtime registries. If you are behind a corporate firewall or proxy, you need to set proxy settings.

For example, if the StarlingX OAM interface or network is behind an http/https proxy, relative to the Docker registries used by StarlingX or applications running on StarlingX, then Docker within StarlingX must be configured to use these http/https proxies.

When Proxy is needed

You must configure proxy settings when:

  • The StarlingX OAM network routes through an HTTP/HTTPS proxy to reach public container registries.

  • Applications running on StarlingX pull images from registries that are only reachable through a proxy.

If your environment has direct access to all required registries, no proxy configuration is needed.

Proxy Architecture Overview

The figure below shows how proxies are used in StarlingX.

|prod| proxy usage

Figure 1: StarlingX proxy usage

Configuration Files

StarlingX uses two proxy-related configurations, labeled a and b in the figure:

Sysadmin shell proxy (file a)

Environment variables for the sysadmin shell session. This file is not required for StarlingX bootstrap or platform operations, but you must manually create it if you access the public network via a proxy.

You must add the following StarlingX specific addresses to the no_proxy list:

Address

Purpose

registry.local

Local image registry

{controller OAM gateway IP/floating IP/host IP}

Controller OAM access

{controller management floating IP/host IP}

Controller management access

{controller cluster gateway IP}

Cluster gateway

10.96.0.1

Kubernetes apiserver cluster IP

10.96.0.10

Kubernetes coredns cluster IP

*.cluster.local

Cluster-internal DNS

Container runtime proxy (file b)

Docker proxy variables configured in the localhost.yml file before Ansible bootstrap. This configuration is required if you access public registries via a proxy. StarlingX specific IP addresses are automatically added to the no_proxy list.

Configure Proxy at Bootstrap

The numbered items correspond to the process flow shown in the figure:

  1. In the localhost.yml file, fill in the Docker proxy section (file b).

  2. The bootstrap process pulls Docker images from either:

    • the public registry using the proxy settings from step 1, or

    • a private registry within the company/organization network.

    The bootstrap process pushes pulled images to registry.local afterwards.

  3. After the Kubernetes API server is running, the bootstrap process communicates with it for further StarlingX configuration. You must ensure the cluster network gateway is set in no_proxy in the sysadmin shell proxy (file a).

  4. After StarlingX provisioning is complete, Docker image pulls use the container runtime proxy (file b). All other operations, including kubectl and system commands, use the sysadmin shell proxy (file a).

For details, refer to Ansible Bootstrap Configurations.

Configure Proxy after Deployment

Use the following commands to add or change proxy settings on a running system.

Note

If a service parameter already exists, use service-parameter-modify instead of service-parameter-add in the commands below.

Set HTTP proxy URL

system service-parameter-add docker proxy http_proxy=http://my.proxy.com:1080
system service-parameter-apply docker

Set HTTPS proxy URL

system service-parameter-add docker proxy https_proxy=https://my.proxy.com:1443
system service-parameter-apply docker

Set no_proxy address list

A no_proxy address list can be provided for registries that do not require a proxy. This list is added to the default no_proxy list derived from localhost, loopback, management, and OAM floating addresses at runtime.

Note

Due to a Docker restriction, each address in the no_proxy list must not use subnet format (e.g., 10.0.0.0/16) and cannot contain wildcards (e.g., *.example.com). Use individual IP addresses or hostnames only.

system service-parameter-add docker proxy no_proxy="1.2.3.4,5.6.7.8"
system service-parameter-apply docker