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_NAMEset, but is empty.JUJU_DISPATCH_PATHlooks like this:actions/do-something- The special
juju-runaction 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
- 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
Contributors: @jack-shaw, @nvinuesa, @ppasotti, @sed-i , @tmihoc