Skip to content
Docs BETA

Allow the address of your provisioner

Goal

For platform teams. In this task you let the control plane call your provisioners when they run on a private network. You set one setting, and you check that registration works.

Before you start

Steps

Know what the control plane refuses

The control plane calls the address of every provisioner. It checks that address twice: when you register or change a provisioner, and again right before each call. It sorts every address into one of three kinds:

Kind of address Addresses Can you allow them?
Always blocked Link-local (169.254.0.0/16 and fe80::/10), multicast (224.0.0.0/4 and ff00::/8), broadcast (255.255.255.255) and unspecified (0.0.0.0/8 and ::) addresses, and the addresses that cloud platforms keep for their own services No
Blocked by default 127.0.0.0/8 and ::1 (loopback), 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 (private), 100.64.0.0/10 (shared address space), fc00::/7 (unique local), fec0::/10 (old site-local), 64:ff9b:1::/48 (NAT64 for local use) Yes, with the setting below
Allowed Every other address Not needed

The control plane resolves a name to its addresses before the check. If one address of the name is in a refused kind, the whole name is refused. The name has 2 seconds to resolve.

Read the error

If you register a provisioner at a private address, the control plane answers 400:

{"detail":"provisioner url points to an address that is not allowed: loopback, private, link-local, multicast and unspecified addresses are refused unless the deployment allows the network","status":400,"title":"Invalid provisioner"}
HTTP 400

The text never repeats the host or the address. If the name does not resolve, the text is provisioner url host could not be resolved to an address.

The dashboard does not show this text. It says that the control plane did not accept the values. It asks you to check the name, the URL, the types and the async limit.

Set the allowed networks

The setting joomiz.provisioners.allowed-networks is a comma-separated list of ranges in CIDR notation. It adds ranges to the allowed addresses. The default is an empty list, so a control plane with no setting calls no address of the second kind.

If your provisioners run in the same cluster as the control plane, allow the range of that cluster, and nothing wider:

joomiz.provisioners.allowed-networks=10.42.0.0/16

In an environment variable, the same setting is:

JOOMIZ_PROVISIONERS_ALLOWEDNETWORKS=10.42.0.0/16

Restart the control plane after you change the setting.

A range must be complete CIDR notation:

Allow a name that resolves to two addresses

A host name can resolve to an IPv4 address and an IPv6 address. Both must be allowed. In a test with a provisioner on the same machine as the control plane, the name resolves to both loopback addresses, so set:

joomiz.provisioners.allowed-networks=127.0.0.0/8,::1/128

Allow the loopback addresses only on a control plane for tests.

Check

  1. Restart the control plane.
  2. Register the provisioner again, as Register a provisioner shows. The answer is 201.
  3. Run joomiz plan for a file that uses a type of this provisioner. The plan shows the answer of the provisioner.

If a range is not valid, the control plane does not start. The error names the setting:

Reason: java.lang.IllegalArgumentException: joomiz.provisioners.allowed-networks contains '0.0.0.0/0', which overlaps the always-blocked range 0.0.0.0/8. Link-local, multicast and unspecified addresses can never be allowed.

Troubleshooting

Symptom Cause Fix
400 and points to an address that is not allowed The address is of a kind that is blocked. Add the range of the provisioner to the setting.
The same 400 after you set the range The name resolves to a second address outside your range. Allow every address of the name. For the loopback addresses, set 127.0.0.0/8,::1/128.
The same 400 for an address that is always blocked No setting allows it. Use another address for the provisioner. No setting allows it.
400 and host could not be resolved The name did not resolve in 2 seconds. Check the name and the DNS of the control plane.
The control plane does not start and names the setting An entry is not valid, or it overlaps an always-blocked range such as 0.0.0.0/0. Write each range in complete CIDR notation, and narrow it.
A plan says the provisioner sent an unexpected response for a provisioner that worked before The name now points to another address, or you changed the setting. The control plane sent no request. Check the registration and the setting.

This is how a plan looks when the control plane refuses to send a call:

error: the control plane could not plan joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  target/cloud-foundry-space: failed — the provisioner sent an unexpected response
    test-foundation (created): failed — the provisioner reported no result for this resource
  managed-resource/postgres: failed — the provisioner sent an unexpected response
    shop-db (created): failed — the provisioner reported no result for this resource
  deployment/cloud-foundry-app: failed — not planned: a resource type it depends on could not be planned
    shop-test-deployment (created): failed — not planned: a resource type it depends on could not be planned
plan failed (revision 7d4ac5d4-7e69-44d5-99d7-e003e5e71152, plan 67a80114-00ae-4501-9f12-b26e5b6d9f74)

The control plane writes the line A provisioner call was not sent: the destination address is not allowed in its log. Look for that line when a plan says the provisioner sent an unexpected response.

An always-blocked address inside a range that you allow stays blocked.

Next

Read how the real provisioners work in The provisioners for Azure DevOps and Cloud Foundry.