Controlling application network ingress via the Juju CLI

Exposing individual application endpoints

Prior to Juju 2.9, the juju expose command would make any port opened by the application’s charm reachable by any IP address (i.e. an ingress CIDR of 0.0.0.0/0). Since Juju 2.9, operators can explicitly specify the list of CIDRs and/or spaces that should be allowed access to the application’s open port ranges.

The aforementioned expose parameters can be specified both at a global application level (targeting any port opened by the charm) as well as on a per-endpoint level (targeting the ports opened for that particular endpoint). Juju 2.9 augments the juju expose command with support for the following set of flags:

  • --endpoints : a comma-delimited list of endpoints to use for selecting the list of port ranges to be exposed.
  • --to-cidrs : a comma-delimited list of CIDRs that should be able to access the selected port ranges.
  • --to-spaces : a comma-delimited list of space names that should be able to access the selected port ranges.

All of the above flags are purely optional. If none of these flags are specified, Juju will fall back to the pre-2.9 behavior and expose all opened port ranges. For instance, running juju expose percona-cluster
is equivalent to running juju expose percona-cluster --to-cidrs 0.0.0.0/0,::/0.

Contrary to pre-2.9 Juju versions where juju expose X is an one-off toggle that simply marks the application as exposed, since juju 2.9, the operator may execute a sequence of juju expose X commands to specify expose settings for individual application endpoints. Note that each juju expose X --endpoints command will overwrite the previous expose settings for each referenced endpoint name.

If a list of spaces is provided via the --to-spaces flag, Juju will consult the current space topology and map each space into a set of CIDRs based on the subnets that constitute each space. This set of CIDRs will be merged together with any operator-specified CIDRS (provided via the --to-cidrs flag) and used for generating the appropriate ingress rules for each exposed application. Juju monitors the space topology for changes and will automatically regenerate the ingress rules for applications as required.

When a juju expose command targets one or more endpoints without specifying any of the --to-cidrs and --to-spaces flags, Juju will once again assume an implicit --to-cidrs 0.0.0.0/0,::/0 argument when evaluating the command.

In the example that follows, the first command exposes all endpoints of percona-cluster. The next command overrides the expose settings for the db-admin endpoint so that any port ranges opened for that endpoint can only be accessed from IP addresses in the 10.0.0.0/24 range.

juju expose percona-cluster
juju expose percona-cluster --endpoints db-admin --to-cidrs 10.0.0.0/24

The full list of the currently configured expose settings can be obtained by running the juju show-application command. For the above example, the command would produce the following output:

juju show-application percona-cluster
percona-cluster:
  ...
  exposed: true
  exposed-endpoints:
    "":
      expose-to-cidrs:
      - 0.0.0.0/0
      - ::/0
    db-admin:
      expose-to-cidrs:
      - 10.0.0.0/24
   ...

The expose settings for the db-admin endpoint can be overridden with another juju expose command targeting the same endpoint:

juju expose percona-cluster --endpoints db-admin --to-cidrs 192.168.0.0/24,192.168.1.0/24

juju show-application percona-cluster
percona-cluster:
  ...
  exposed: true
  exposed-endpoints:
    "":
      expose-to-cidrs:
      - 0.0.0.0/0
      - ::/0
    db-admin:
      expose-to-cidrs:
      - 192.168.0.0/24
      - 192.168.1.0/24
  ...

Unexposing individual application endpoints

Since Juju 2.9, the juju unexpose command also supports an optional --endpoints flag which may be provided by operators to delete the expose settings for a list of endpoints. If the command is invoked without the --endpoints flag, all expose settings will be deleted and the application will be marked as unexposed.

Juju will automatically mark the application as unexposed when all expose settings are deleted.

Continuing the above example, running juju unexpose percona-cluster --endpoints db-admin will block access to any port ranges opened for the db-admin endpoint but still allow access to ports opened for all other endpoints:

juju unexpose percona-cluster --endpoints db-admin

juju show-application percona-cluster
percona-cluster:
  ...
  exposed: true
  exposed-endpoints:
    "":
      expose-to-cidrs:
      - 0.0.0.0/0
      - ::/0
  ...