Create an ingress gateway token

This topic describes how to create a token to enable an ingress gateway to register.

Introduction

Gateways must present a token linked to policies that grant the appropriate set of permissions in order to register into the catalog and to route to other services in a mesh.

Requirements

Core ACL functionality is available in all versions of Consul.

The ingress gateway token must be linked to policies that grant the following permissions:

service:write to allow the ingress gateway to register into the catalog
service:read for all services and node:read for all nodes in order to discover and route to services
agent:read to enable the consul connect envoy CLI command to automatically discover gRPC settings from the Consul agent. If this command is not used to start the gateway or if the Consul agent uses the default gRPC settings, then you can omit the agent:read permission.

Authentication

You must provide an ACL token linked to a policy with acl:write permissions to create and modify ACL tokens and policies using the CLI or API.

You can provide the token manually using the -token option on the command line, but we recommend setting the CONSUL_HTTP_TOKEN environment variable to simplify your workflow:

$ export CONSUL_HTTP_TOKEN=<acl-token-secret-id>

The Consul CLI automatically reads the CONSUL_HTTP_TOKEN environment variable so that you do not have to pass the token to every Consul CLI command.

To authenticate calls to the Consul HTTP API, you must provide the token in the X-Consul-Token header for each call:

$ curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" ...

To learn about alternative ways to authenticate, refer to the following documentation:

Consul CE

To create a token for the ingress gateway, you must define a policy, register the policy with Consul, and link the policy to a token.

Define a policy

You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to ACL Rules for details about all of the rules you can use in your policies.

The following example policy is defined in a file. The policy grants the ingress gateway the appropriate permissions to register as a service named ingress-gateway and to operate as an ingress gateway.

service "ingress-gateway" {
  policy = "write"
}
node_prefix "" {
  policy = "read"
}
service_prefix "" {
  policy = "read"
}
agent_prefix "" {
  policy = "read"
}

{
  "agent_prefix": {
    "": [{
      "policy": "read"
    }]
  },
  "node_prefix": {
    "": [{
      "policy": "read"
    }]
  },
  "service": {
    "ingress-gateway": [{
      "policy": "write"
    }]
  },
  "service_prefix": {
    "": [{
      "policy": "read"
    }]
  }
}

Register the policy with Consul

After defining the policy, you can register the policy with Consul using the command line or API endpoint.

The following commands create the ACL policy and token.

Run the consul acl policy create command and specify the policy rules to create a policy. The following example registers a policy defined in igw-register.hcl:

$ consul acl policy create \
    -name "igw-register" -rules @igw-register.hcl \
    -description "Ingress gateway policy"

Refer to Consul ACL Policy Create for details about the consul acl policy create command.

Send a PUT request to the /acl/policy endpoint and specify the policy rules in the request body to create a policy. The following example registers the policy defined in igw-register.hcl. You must embed policy rules in the Rules field of the request body.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "igw-register",
  "Description": "Ingress gateway policy",
  "Rules": "service \"ingress-gateway\" {\n  policy = \"write\"\n}\nnode_prefix \"\" {\n  policy = \"read\"\n}\nservice_prefix \"\" {\n  policy = \"read\"\n}\nagent_prefix \"\" {\n  policy = \"read\"\n}\n"
}'

Refer to ACL Policy HTTP API for additional information about using the API endpoint.

Link the policy to a token

After registering the policy into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an auth method.

Run the consul acl token create command and specify the policy name or ID to create a token linked to the policy. Refer to Consul ACL Token Create for details about the consul acl token create command.

The following command creates the ACL token linked to the policy igw-register.

$ consul acl token create \
    -description "Ingress gateway token" \
    -policy-name "igw-register"

Send a PUT request to the /acl/token endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to ACL Token HTTP API for additional information about using the API endpoint.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "igw-register"
    }
  ]
}'

Consul Enterprise

To create a token for the ingress gateway, you must define a policy, register the policy with Consul, and link the policy to a token.

Define a policy

You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to ACL Rules for details about all of the rules you can use in your policies.

You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes.

The following example policy is defined in a file. The policy allows an ingress gateway to register as a service named ingress-gateway in the ptn1 partition and ns1 namespace. The policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the default namespace.

partition "ptn1" {
  namespace "ns1" {
    service "ingress-gateway" {
      policy = "write"
    }
    node_prefix "" {
      policy = "read"
    }
    service_prefix "" {
      policy = "read"
    }
  }
  namespace "default" {
    agent_prefix "" {
      policy = "read"
    }
  }
}

{
  "partition": {
    "ptn1": [{
      "namespace": {
        "default": [{
          "agent_prefix": {
            "": [{
              "policy": "read"
            }]
          }
        }],
        "ns1": [{
          "node_prefix": {
            "": [{
              "policy": "read"
            }]
          },
          "service": {
            "ingress-gateway": [{
              "policy": "write"
            }]
          },
          "service_prefix": {
            "": [{
              "policy": "read"
            }]
          }
        }]
      }
    }]
  }
}

Register the policy with Consul

After defining the policy, you can register the policy with Consul using the command line or API endpoint.

The following commands create the ACL policy and token.

Run the consul acl policy create command and specify the policy rules to create a policy. The following example registers a policy defined in igw-register.hcl:

You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. The following example creates the policy in the default namespace in the ptn1 partition. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the default namespace.

$ consul acl policy create -partition "ptn1" -namespace "default" \
  -name "igw-register" -rules @igw-register.hcl \
  -description "Ingress gateway policy"

Refer to Consul ACL Policy Create for details about the consul acl policy create command.

You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition ptn1 and namespace ns1. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the default namespace.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "igw-register",
  "Description": "Ingress gateway policy",
  "Partition": "ptn1",
  "Namespace": "default",
  "Rules": "partition \"ptn1\" {\n  namespace \"ns1\" {\n    service \"ingress-gateway\" {\n      policy = \"write\"\n    }\n    node_prefix \"\" {\n      policy = \"read\"\n    }\n    service_prefix \"\" {\n      policy = \"read\"\n    }\n  }\n  namespace \"default\" {\n    agent_prefix \"\" {\n      policy = \"read\"\n    }\n  }\n}\n"
}'

Refer to ACL Policy HTTP API for additional information about using the API endpoint.

Link the policy to a token

You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition ptn1 and namespace default. The example policy contains permissions for resources in multiple namespaces. You must create ACL tokens linked to policies that grant permissions for multiple namespaces in the default namespace.

$ consul acl token create -partition "ptn1" -namespace "default" \
    -description "Ingress gateway token" \
    -policy-name "igw-register"

You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the ingress gateway is registered. The following example creates the token in the partition ptn1 and namespace default.

$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "igw-register"
    }
  ],
  "Partition": "ptn1",
  "Namespace": "default"
}'