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.

Note

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
CLOUD_API_VERSION
JUJU_ACTION_NAME
JUJU_ACTION_TAG
JUJU_ACTION_UUID
JUJU_AGENT_CA_CERT
JUJU_AGENT_SOCKET_ADDRESS
JUJU_AGENT_SOCKET_NETWORK
JUJU_API_ADDRESSES
JUJU_AVAILABILITY_ZONE
JUJU_CHARM_DIR
JUJU_CHARM_FTP_PROXY
JUJU_CHARM_HTTPS_PROXY
JUJU_CHARM_HTTP_PROXY
JUJU_CHARM_NO_PROXY
JUJU_CONTEXT_ID
JUJU_DEPARTING_UNIT
JUJU_HOOK_NAME
JUJU_MACHINE_ID
JUJU_METER_INFO
JUJU_METER_STATUS
JUJU_MODEL_NAME
JUJU_MODEL_UUID
JUJU_NOTICE_ID
JUJU_NOTICE_KEY
JUJU_NOTICE_TYPE
JUJU_PRINCIPAL_UNIT
JUJU_RELATION
JUJU_RELATION_ID
JUJU_REMOTE_APP
JUJU_REMOTE_UNIT
JUJU_SECRET_ID
JUJU_SECRET_LABEL
JUJU_SECRET_REVISION
JUJU_SLA
JUJU_STORAGE_ID
JUJU_STORAGE_KIND
JUJU_STORAGE_LOCATION
JUJU_TARGET_BASE
JUJU_TARGET_SERIES (deprecated in Juju 3, to be removed in Juju 4; please use JUJU_TARGET_BASE instead)
JUJU_UNIT_NAME
JUJU_VERSION