Charm environment variables

When a charm runs, it will gather all sorts of information from its execution context. These are environment variables. They are used to parametrise the charm’s runtime.

Charms written with the operator framework benefit from the various abstraction levels on top of the environment variables, so charm authors rarely (if at all) need to work with them directly.

Depending on the event type, there might be some differences in what environment variables are set. For example, in a pebble-ready event they would be as below, where the JUJU_WORKLOAD_NAME environment variable is actually unique to this event.

{
 'APT_LISTCHANGES_FRONTEND': 'none',
 'CHARM_DIR': '/var/lib/juju/agents/unit-bare-0/charm',
 'CLOUD_API_VERSION': '1.23.0',
 'DEBIAN_FRONTEND': 'noninteractive',
 'JUJU_AGENT_SOCKET_ADDRESS': '@/var/lib/juju/agents/unit-bare-0/agent.socket',
 'JUJU_AGENT_SOCKET_NETWORK': 'unix',
 'JUJU_API_ADDRESSES': '10.152.183.4:17070 '
                       'controller-service.controller-charm-dev.svc.cluster.local:17070',
 'JUJU_AVAILABILITY_ZONE': '',
 'JUJU_CHARM_DIR': '/var/lib/juju/agents/unit-bare-0/charm',
 'JUJU_CHARM_FTP_PROXY': '',
 'JUJU_CHARM_HTTPS_PROXY': '',
 'JUJU_CHARM_HTTP_PROXY': '',
 'JUJU_CHARM_NO_PROXY': '127.0.0.1,localhost,::1',
 'JUJU_CONTEXT_ID': 'bare/0-workload-pebble-ready-1918120275707858680',
 'JUJU_DISPATCH_PATH': 'hooks/workload-pebble-ready',
 'JUJU_HOOK_NAME': 'workload-pebble-ready',
 'JUJU_MACHINE_ID': '',
 'JUJU_METER_INFO': 'not set',
 'JUJU_METER_STATUS': 'AMBER',
 'JUJU_MODEL_NAME': 'welcome',
 'JUJU_MODEL_UUID': 'cdac5656-2423-4388-8f30-41854b4cca7d',
 'JUJU_PRINCIPAL_UNIT': '',
 'JUJU_SLA': 'unsupported',
 'JUJU_UNIT_NAME': 'bare/0',
 'JUJU_VERSION': '2.9.29',
 'JUJU_WORKLOAD_NAME': 'workload',
 'KUBERNETES_PORT': 'tcp://10.152.183.1:443',
 'KUBERNETES_PORT_443_TCP': 'tcp://10.152.183.1:443',
 'KUBERNETES_PORT_443_TCP_ADDR': '10.152.183.1',
 'KUBERNETES_PORT_443_TCP_PORT': '443',
 'KUBERNETES_PORT_443_TCP_PROTO': 'tcp',
 'KUBERNETES_SERVICE_HOST': '10.152.183.1',
 'KUBERNETES_SERVICE_PORT': '443',
 'KUBERNETES_SERVICE_PORT_HTTPS': '443',
 'LANG': 'C.UTF-8',
 'OPERATOR_DISPATCH': '1',
 'PATH': '/var/lib/juju/tools/unit-bare-0:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/charm/bin',
 'PWD': '/var/lib/juju/agents/unit-bare-0/charm',
 'PYTHONPATH': 'lib:venv',
 'TERM': 'tmux-256color',
}

The environment variables for a specific event can be obtained by running juju debug-hooks <unit name> and waiting for the desired event to fire. If the next prompt looks as below

root@database-0:/var/lib/juju#

this means that we are still waiting for an event to occur. As soon as that happens, the prompt will look similar to the below

root@database-0:/var/lib/juju/agents/unit-database-0/charm#

and this means we’re inside the charm execution context. At this point, typing printenv will print out the environment variables.

Event variables

Core hooks

JUJU_HOOK_NAME JUJU_DISPATCH_PATH Notes
'workload-pebble-ready' 'hooks/workload-pebble-ready' This is the only event that sets JUJU_WORKLOAD_NAME.
'update-status' 'hooks/update-status'
'install' 'hooks/install'
'leader-elected' 'hooks/leader-elected'
'leader-settings-changed' 'hooks/leader-settings-changed'
'start' 'hooks/start'
'stop' 'hooks/stop'
'remove' 'hooks/remove'
'config-changed' 'hooks/config-changed'
'upgrade-charm' 'hooks/upgrade-charm'

Relation hooks

Only relation hooks set JUJU_RELATION, JUJU_RELATION_ID, JUJU_REMOTE_UNIT and JUJU_REMOTE_APP.

JUJU_HOOK_NAME JUJU_DISPATCH_PATH Notes
'<name>-relation-created' 'hooks/<name>-relation-created' JUJU_REMOTE_UNIT is set but is empty
'<name>-relation-joined' 'hooks/<name>-relation-joined'
'<name>-relation-changed' 'hooks/<name>-relation-changed'
'<name>-relation-departed' 'hooks/<name>-relation-departed' This is the only event that sets JUJU_DEPARTING_UNIT.
'<name>-relation-broken' 'hooks/<name>-relation-broken' JUJU_REMOTE_UNIT is set but is empty

Storage hooks

Only storage hooks set JUJU_STORAGE_LOCATION, JUJU_STORAGE_KIND and JUJU_STORAGE_ID.

JUJU_HOOK_NAME JUJU_DISPATCH_PATH Notes
'<name>-storage-attached' 'hooks/<name>-storage-attached'
'<name>-storage-detaching' 'hooks/<name>-storage-detaching'

Actions

Only actions set JUJU_ACTION_NAME, JUJU_ACTION_TAG and JUJU_ACTION_UUID.

  • JUJU_HOOK_NAME set, but is empty.
  • JUJU_DISPATCH_PATH looks like this: actions/do-something
  • The special juju-run action can be used to print out environment variables for its own context: juju run --unit my-app/0 -- env

Secrets

All secrets hooks set JUJU_SECRET_ID and JUJU_SECRET_LABEL. Only secret-expired, secret-rotate and secret-remove also set JUJU_SECRET_REVISION.

Do note that the JUJU_SECRET_LABEL will be set to some non-empty value only if the secret at hand has a label at the time the event is emitted by the agent.

JUJU_HOOK_NAME Notes
'secret-changed' This is the only secrets hook that does not set JUJU_SECRET_REVISION
'secret-expired'
'secret-remove'
'secret-rotate'

List of charm environment variables

Source (the HookVars function)

  • CHARM_DIR
  • JUJU_CHARM_DIR
  • JUJU_CONTEXT_ID
  • JUJU_HOOK_NAME
  • JUJU_AGENT_SOCKET_ADDRESS
  • JUJU_AGENT_SOCKET_NETWORK
  • JUJU_UNIT_NAME
  • JUJU_MODEL_UUID
  • JUJU_MODEL_NAME
  • JUJU_API_ADDRESSES
  • JUJU_SLA
  • JUJU_MACHINE_ID
  • JUJU_PRINCIPAL_UNIT
  • JUJU_AVAILABILITY_ZONE
  • JUJU_VERSION
  • CLOUD_API_VERSION
  • JUJU_CHARM_HTTP_PROXY
  • JUJU_CHARM_HTTPS_PROXY
  • JUJU_CHARM_FTP_PROXY
  • JUJU_CHARM_NO_PROXY
  • JUJU_AGENT_CA_CERT
  • JUJU_METER_STATUS
  • JUJU_METER_INFO
  • JUJU_RELATION
  • JUJU_RELATION_ID
  • JUJU_REMOTE_UNIT
  • JUJU_REMOTE_APP
  • JUJU_DEPARTING_UNIT
  • JUJU_ACTION_NAME
  • JUJU_ACTION_UUID
  • JUJU_ACTION_TAG
  • JUJU_NOTICE_ID
  • JUJU_NOTICE_TYPE
  • JUJU_NOTICE_KEY
  • JUJU_TARGET_BASE
  • JUJU_TARGET_SERIES
  • JUJU_SECRET_ID
  • JUJU_SECRET_LABEL
  • JUJU_SECRET_REVISION
  • JUJU_STORAGE_ID
  • JUJU_STORAGE_LOCATION
  • JUJU_STORAGE_KIND

Last updated 21 hours ago. Help improve this document in the forum.