Itential Automation GatewayDeploy and manageConfigure

Configure client profiles

IAG 5.4+

Client profiles let you define named connection configurations in gateway.conf and switch between them using the --profile flag — without editing the config file or setting environment variables between commands. Use profiles when you manage multiple gateway clusters, such as production, staging, and development environments, from a single workstation.

Define profiles in gateway.conf

Profiles are defined as [client:profile_name] sections in gateway.conf. Each profile inherits any settings not explicitly defined from the base [client] section, so you only need to specify values that differ from the base configuration.

Profile sections support the following properties:

PropertyDescription
hostGateway hostname or IP address
portGateway port number
api_keyAPI key for authentication
certificate_filePath to the client certificate file
private_key_filePath to the client private key file
use_tlsWhether to use TLS for the connection

Profile names are alphanumeric, case-insensitive, and normalized to lowercase internally — production, Production, and PRODUCTION all resolve to the same profile.

1[client]
2host = localhost
3port = 50051
4
5[client:production]
6host = gw.prod.example.com
7certificate_file = ~/.gateway.d/certs/prod.crt
8private_key_file  = ~/.gateway.d/certs/prod.key
9
10[client:staging]
11host = gw.staging.example.com

In this example, the staging profile inherits port = 50051 from the base [client] section and only overrides host. The production profile overrides host and specifies its own certificate files.

Use a profile

Pass --profile <profile_name> to any iagctl command to use a named profile:

$# Uses [client] section (localhost)
$iagctl get services
$
$# Uses [client:production]
$iagctl --profile production get services
$
$# Uses [client:staging]
$iagctl --profile staging get services

Without --profile, iagctl uses the base [client] section as before — existing configurations require no changes.

Override profile settings with environment variables

You can override individual profile settings using environment variables following the pattern GATEWAY_CLIENT_<PROFILE>_<SETTING>, where <PROFILE> is the uppercase profile name and <SETTING> is the uppercase setting name.

For example, to override the host for the production profile:

$export GATEWAY_CLIENT_PRODUCTION_HOST=gw.prod-us-east.example.com
$iagctl --profile production get services

Profile-specific environment variables take precedence over all other configuration sources. The full precedence order for any setting is:

  1. Profile-specific environment variable (GATEWAY_CLIENT_<PROFILE>_<SETTING>)
  2. Profile config section ([client:profile_name])
  3. Base environment variable (GATEWAY_CLIENT_<SETTING>)
  4. Base config section ([client])
  5. Default value

Verify the active configuration

Run iagctl version --show-config to display the resolved effective configuration after profile selection:

$iagctl --profile production version --show-config

The output reflects the fully resolved configuration — inherited values from the base [client] section, overrides from the profile section, and any environment variable overrides applied on top.

Learn more