Deploy Connectivity Link

Set up DNS access, create a Gateway object, and set default policies to complete your Connectivity Link deployment. Follow these steps on each cluster where you want to deploy Connectivity Link.

Workflow for providing a platform

You can use Connectivity Link to set up ingress Gateway objects on OpenShift Container Platform clusters in specific regions. You can configure all policies identically on all Gateway objects for consistency.

For example, configure DNS policies to ensure that customers in Brazil are routed to the South American data center and so on. You can also configure TLS, authentication and authorization, and rate-limiting policies to ensure that gateway security, performance, and monitoring all conform to your standards.

Connect gateways and load balance

You must start by creating at least one Gateway object. If Gateway objects exist, you can move on to configuring access policies for those Gateway objects.

You can connect Gateway objects by creating a DNS policy and configuring a global load balancing strategy. DNS records are reconciled with your cloud DNS provider automatically, whether in a single-cluster or multicluster environment. You can use the following tools:

  • Automatic DNS configuration

  • Multiple DNS providers

  • DNS-based load balancing, such as round-robin, weighted, and geo-based

  • Single or multicluster ready

Secure Gateways

After you create your Gateway objects, secure them. You can secure Gateway objects by using a TLS policy that automatically generates certificate requests for the host names specified in your gateway. You can also set up application security defaults and overrides by using authentication and authorization policies and rate-limiting policies. You can use the following tools:

  • TLS: Automatic certificate requests and ACME providers

  • Auth policies

  • Rate-limiting: Global rate-limiting, external IDPs, default and overrides

Observe Gateways

After you create and secure your Gateway objects, you can configure your observability stack. Observe your connectivity and runtime metrics by using dashboards and alerts. For example, configure metrics for policy compliance and governance, resource consumption, error rates, request latency and throughput.

Set up your environment

You can set up your environment variables and deploy a sample application on your OpenShift Container Platform cluster. In this example, a demonstration application is used.

Note

The Toystore application is an example only and is not intended for production use.
Prerequisites

  • You installed Connectivity Link on at least one OpenShift Container Platform cluster.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

  • You know the name and namespace of the gateway you want to connect your application to.

Procedure

  1. Set the following environment variable by running the following command:

    $ export KUADRANT_GATEWAY_NS=api-gateway \
  export KUADRANT_GATEWAY_NAME=ingress-gateway \
  export KUADRANT_DEVELOPER_NS=toystore \
  export KUADRANT_AWS_ACCESS_KEY_ID=xxxx \
  export KUADRANT_AWS_SECRET_ACCESS_KEY=xxxx \
  export KUADRANT_ZONE_ROOT_DOMAIN=example.com \
  export KUADRANT_CLUSTER_ISSUER_NAME=self-signed

    • KUADRANT_GATEWAY_NS: Namespace for your gateway in OpenShift Container Platform.

    • KUADRANT_GATEWAY_NAME: Name of your gateway in OpenShift Container Platform.

    • KUADRANT_DEVELOPER_NS: Namespace for the example Toystore app in OpenShift Container Platform. You can replace this value with the name of the application you want to use.

    • KUADRANT_AWS_ACCESS_KEY_ID: DNS provider access key ID. In this example, AWS is used. You can replace this value with your DNS provider information.

    • KUADRANT_AWS_SECRET_ACCESS_KEY: DNS provider secret access key with permissions to manage your DNS zone. In this example, AWS is used. You can replace this value with your DNS provider information.

    • KUADRANT_ZONE_ROOT_DOMAIN: The root domain associated with your DNS zone ID. In this example, the OpenShift Container Platform secret containing the credentials for the DNS provider is AWS Route53. You can replace this value with your DNS provider information.

    • KUADRANT_CLUSTER_ISSUER_NAME: Name of the certificate authority or the issuer for TLS certificates.

  2. Create the namespace for the application by running the following command:

    $ oc create ns ${KUADRANT_DEVELOPER_NS}

  3. Deploy your application to the namespace you specified by running the following command:

    $ oc apply -f https://raw.githubusercontent.com/Kuadrant/Kuadrant-operator/main/examples/toystore/toystore.yaml -n ${KUADRANT_DEVELOPER_NS}

    You can replace the Toystore application with the path to the one you want to use.

Set up a DNS provider secret

You can create access to the DNS zones that Connectivity Link can use by configuring your external DNS provider credentials. After you set up your Secret resource, create your Gateway CR and secure it.

You can then restrict access to only the DNS zones that you want Connectivity Link to manage by setting a DNSPolicy CR.

Important

You must apply the following Secret to each cluster.
Prerequisites

  • You installed Connectivity Link on one or more clusters.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

Procedure

  1. Create the namespace where you want your Gateway CR applied in by running the following command:

    $ oc create ns ${KUADRANT_GATEWAY_NS}

  2. Create the Secret credentials in the same namespace as the Gateway CR namespace by running the following command:

    $ oc -n ${KUADRANT_GATEWAY_NS} create secret generic <aws_credentials> \
  --type=kuadrant.io/aws \
  --from-literal=AWS_ACCESS_KEY_ID=$KUADRANT_AWS_ACCESS_KEY_ID \
  --from-literal=AWS_SECRET_ACCESS_KEY=$KUADRANT_AWS_SECRET_ACCESS_KEY

    Replace <aws_credentials> with the secret you want to use.

Next step

  • Configure your TLS issuer and policy.

Create your Gateway object

You must deploy a Gateway object in your OpenShift Container Platform cluster to begin setting up the infrastructure used by application developers. The Gateway object is the instantiation of your entry point.

The Gateway object causes the controller to provision a load balancer with specific ports and security credentials.

Important

For Connectivity Link to balance traffic by using DNS across clusters, you must define your Gateway object with a shared hostname. You can define the shared hostname by using an HTTPS listener with a wildcard hostname based on the root domain. You must apply these resources to each cluster that you want to use them.
Prerequisites

  • You installed Connectivity Link on one or more clusters.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

Procedure

  1. Create a Gateway custom resource (CR), such as {KUADRANT_GATEWAY_NAME}.yaml, that has the following information:

    Example Gateway CR
    apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${KUADRANT_GATEWAY_NAME}
  namespace: ${KUADRANT_GATEWAY_NS}
  labels:
    kuadrant.io/gateway: "true"
spec:
    gatewayClassName: openshift-default
    listeners:
    - allowedRoutes:
        namespaces:
          from: All
      hostname: "api.${KUADRANT_ZONE_ROOT_DOMAIN}"
      name: api
      port: 443
      protocol: HTTPS
      tls:
        certificateRefs:
        - group: ""
          kind: Secret
          name: api-${KUADRANT_GATEWAY_NAME}-tls
        mode: Terminate
    Important

    If you require cryptographic identity verification, see "Create a Gateway object for use with the X.509 format" for a Gateway object example to use instead of this default.

  2. Apply the Gateway CR by running the following command:

    $ oc apply -f {KUADRANT_GATEWAY_NAME}.yaml
Verification

  1. Check the status of your Gateway object by running the following command:

    $ oc get gateway ${KUADRANT_GATEWAY_NAME} -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}{"\n"}{.status.conditions[?(@.type=="Programmed")].message}'
    Example output
    Resource accepted
Resource programmed, assigned to service(s) ${KUADRANT_GATEWAY_NAME}.${KUADRANT_GATEWAY_NS}.svc.cluster.local:443

  2. Check the status of your HTTPS listener by running the following command:

    $ oc get gateway ${KUADRANT_GATEWAY_NAME} -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.listeners[0].conditions[?(@.type=="Programmed")].message}'

    The HTTPS listener exists, but is not programmed or ready to accept traffic because you do not have valid certificates available.

Next step

  • Create a TLSPolicy CR to program your HTTPS listener to accept traffic.

Add a TLS certificate issuer

To secure communication to your Gateway object, you must define a certificate authority (CA) as an issuer for TLS certificates.

Configure a TLSPolicy custom resource (CR) to automatically provision TLS certificates based on Gateway object listener hosts by using integration with cert-manager Operator for Red Hat OpenShift and ACME providers.

Note

You can use any certificate issuer supported by cert-manager. In multicluster environments, you must add your TLS issuer in each OpenShift Container Platform cluster.

If you set up your Gateway CR to use HTTP instead of than HTTPS, setting up TLS and a TLSPolicy CR are not required.

Prerequisites

  • You installed Connectivity Link on one or more clusters.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

  • You created and applied a Gateway object.

  • You created and applied an HTTPRoute object.

Procedure

  1. Before adding a TLS certificate issuer, create the secret credentials in the cert-manager namespace by running the following command:

    $ oc -n cert-manager create secret generic <dns_provider_credentials> \
  --type=kuadrant.io/aws \
  --from-literal=AWS_ACCESS_KEY_ID=$KUADRANT_AWS_ACCESS_KEY_ID \
  --from-literal=AWS_SECRET_ACCESS_KEY=$KUADRANT_AWS_SECRET_ACCESS_KEY

    Replace <dns_provider_credentials> with the secret you want to use. This example uses Amazon Web Services (AWS).

  2. Create a TLS certificate issuer resource, such as {KUADRANT_CLUSTER_ISSUER_NAME}.yaml, that has the following information:

    apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: ${KUADRANT_CLUSTER_ISSUER_NAME}
spec:
  selfSigned: {}

  3. Apply the ClusterIssuer CR by running the following command:

    $ oc apply -f {KUADRANT_CLUSTER_ISSUER_NAME}.yaml
Verification

  • Verify that the ClusterIssuer object is ready by running the following command:

    $ oc wait clusterissuer/${KUADRANT_CLUSTER_ISSUER_NAME} --for=condition=ready=true
Set a TLS policy

Create a TLSPolicy custom resource (CR) for your gateway to regulate the ciphers a client can use when connecting to the server. This ensures that Connectivity Link components use cryptographic libraries that do not allow known insecure protocols, ciphers, or algorithms.

If you set up your Gateway CR to use HTTP instead of than HTTPS, setting up TLS and a TLSPolicy CR are not required.

Prerequisites

  • You installed Connectivity Link on one or more clusters.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

  • You created and applied a Gateway object.

Procedure

  1. Create a TLSPolicy custom resource (CR) such as <toystore_tls.yaml>, that has the following information:

    Example TLSPolicy CR
    apiVersion: kuadrant.io/v1
kind: TLSPolicy
metadata:
  name: ${KUADRANT_GATEWAY_NAME}-tls
  namespace: ${KUADRANT_GATEWAY_NS}
spec:
  targetRef:
    name: ${KUADRANT_GATEWAY_NAME}
    group: gateway.networking.k8s.io
    kind: Gateway
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: ${KUADRANT_CLUSTER_ISSUER_NAME}

  2. Apply your TLSPolicy CR by running the following command:

    $ oc apply -f <toystore_tls.yaml>

    Replace <toystore> with the name of your TLSPolicy object.

Verification

  • Verify that your TLSPolicy object has an Accepted and Enforced status by running the following command:

    $ oc get tlspolicy ${KUADRANT_GATEWAY_NAME}-tls -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}{"\n"}{.status.conditions[?(@.type=="Enforced")].message}'

    This might take a few minutes.

    Example output
    TLSPolicy has been accepted
TLSPolicy has been successfully enforced

Set the DNS policy

Control multicluster ingress by using DNS to bring traffic to your gateways with DNSPolicy custom resources (CRs). Setting a DNS policy automates the link between your Gateway IP address and a human-readable hostname.

Create and apply a default DNSPolicy custom resource (CR) to ensure consistency and cleanup. You can standardized naming by creating a pattern for developers who need URLs, manage time-to-live values, and set up automatic cleanup of unused DNS records.

Prerequisites

  • You installed Connectivity Link on at least one OpenShift Container Platform cluster.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

  • You created a DNS-provider Secret object.

  • You created a Gateway object.

Procedure

  1. Create a DNSPolicy custom resource (CR), for example, {KUADRANT_GATEWAY_NAME}-dnspolicy.yaml, that includes the following information:

    apiVersion: kuadrant.io/v1
kind: DNSPolicy
metadata:
  name: <${KUADRANT_GATEWAY_NAME}-dnspolicy>
  namespace: <${KUADRANT_GATEWAY_NS}>
spec:
  healthCheck:
    failureThreshold: 3
    interval: 1m
    path: /health
  loadBalancing:
    defaultGeo: true
    geo: GEO-NA
    weight: 120
  targetRef:
    name: <${KUADRANT_GATEWAY_NAME}>
    group: gateway.networking.k8s.io
    kind: Gateway
  providerRefs:
  - name: <dns_provider_credentials>

    • Replace <{KUADRANT_GATEWAY_NAME}-dnspolicy.yaml> with the environment variable you defined.

    • Replace <{KUADRANT_GATEWAY_NS}> with the environment variable you defined.

    • spec.loadBalancing.geo: Defines a geographically relevant load balancer. In this example, GEO-NA is used. Change this to match your requirements.

    • spec.providerRefs: Replace <dns_provider_credentials> with a reference to the OpenShift Container Platform secret containing the credentials for your DNS provider.

  2. Apply the DNSPolicy CR by running the following command:

    $ oc apply -f <{KUADRANT_GATEWAY_NAME}_dnspolicy.yaml> -n <gateway_namespace>

    • Replace <{KUADRANT_GATEWAY_NAME}_dnspolicy.yaml> with the filename you used.

    • Replace <gateway_namespace> with name of the OpenShift Container Platform namespace where the Gateway object is applied.

Verification

  1. Verify that your DNSPolicy object has a status of Accepted and Enforced by running the following command:

    $ oc get dnspolicy <${KUADRANT_GATEWAY_NAME}-dnspolicy> -n <${KUADRANT_GATEWAY_NS}> -o=jsonpath='{.status.conditions[?(@.type=="SubResourcesHealthy")].message}'

    • Replace <{KUADRANT_GATEWAY_NAME}_dnspolicy.yaml> with the filename you used.

    • Replace <{KUADRANT_GATEWAY_NS}> with the environment variable you used.

    • This process might take a few minutes.

  2. Check the status of the DNS health checks that are enabled on your DNS policy by running the following command:

    $ oc get dnspolicy <${KUADRANT_GATEWAY_NAME}_dnspolicy> -n <${KUADRANT_GATEWAY_NS}> -o=jsonpath='{.status.conditions[?(@.type=="SubResourcesHealthy")].message}'

    • Replace <{KUADRANT_GATEWAY_NAME}_dnspolicy.yaml> with the filename you used.

    • Replace <{KUADRANT_GATEWAY_NS}> with the environment variable you used.

    • These health checks flag a published endpoint as healthy or unhealthy based on the defined configuration. When unhealthy, an endpoint is not published if it has not already been published to the DNS provider. An endpoint is only unpublished if it is part of an A record that has more than one value. You can see the endpoint status for all cases in the DNSPolicy object status.

Set the default AuthPolicy custom resource

You can use Auth policy objects to define who you allow to connect to your services. Configure a Connectivity Link AuthPolicy custom resource (CR) to use external auth providers. You can ensure that different clusters exposing the same API can authenticate with the same permissions.

Tip

Apply an AuthPolicy custom resource (CR) with a deny-all policy to create a zero-trust environment. Using a zero-trust AuthPolicy object means that no traffic flows unless a specific allow rule is set. Every connection request must be authenticated. You can prevent the accidental exposing of services by using a deny-all policy.

In a zero-trust environment, every application with an HTTPRoute or GRPCRoute CR exposed by an application developer must also have an attached route-level AuthPolicy CR. You can attach multiple AuthPolicy objects to your Gateway, HTTPRoute, and GRPCRoute CRs.

Prerequisites

  • You installed Connectivity Link on one or more clusters.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

  • You created a Gateway object.

  • You created an HTTPRoute or GRPCRoute object.

Procedure

  1. Create a default AuthPolicy CR, such as gateway_name-auth.yaml, with a deny-all setting for your Gateway object:

    Example AuthPolicy CR
    apiVersion: kuadrant.io/v1
kind: AuthPolicy
metadata:
  name: ${KUADRANT_GATEWAY_NAME}-auth
  namespace: ${KUADRANT_GATEWAY_NS}
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: ${KUADRANT_GATEWAY_NAME}
  defaults:
   when:
     - predicate: "request.path != '/health'"
   rules:
    authorization:
      deny-all:
        opa:
          rego: "allow = false"
    response:
      unauthorized:
        headers:
          "content-type":
            value: application/json
        body:
          value: |
            {
              "error": "Forbidden",
              "message": "Access denied by default by the gateway operator. If you are the administrator of the service, create a specific auth policy for the route."
            }

  2. Apply your AuthPolicy CR by running the following command:

    $ oc apply -f <gateway_name_auth.yaml>

    • Replace <gateway_name_auth.yaml> with the name of your AuthPolicy CR.

Verification

  1. Check that your AuthPolicy has Accepted and Enforced status by running the following command:

    $ oc get authpolicy ${KUADRANT_GATEWAY_NAME}-auth -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}{"\n"}{.status.conditions[?(@.type=="Enforced")].message}'
    Example output
    AuthPolicy has been accepted
AuthPolicy has been successfully enforced

  2. Test your AuthPolicy CR by running the following curl command:

    $ curl -H 'Authorization: APIKEY ndyBzreUzF4zqDQsqSPMHkRhriEOtcRx' http://api.example.com:8000/hello
    Example output
    HTTP/1.1 200 OK

Set a default rate-limit policy

As a platform engineer, set up rate limiting to ensure that you are defining how much any one service can use the Gateway object’s connection resources. Rate limits also protect backend services from excessive requests.

You can attach multiple RateLimitPolicy objects to your Gateway and HTTPRoute CRs.

Prerequisites

  • You installed Connectivity Link on one or more clusters.

  • You have a shared Redis-based datastore.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

  • You created a Gateway object.

  • You created an HTTPRoute object.

Procedure

  1. Create a default RateLimitPolicy custom resource (CR), for example, gateway_name-rlp.yaml, that has the following information:

    Example RateLimitPolicy CR
    apiVersion: kuadrant.io/v1
kind: RateLimitPolicy
metadata:
  name: ${KUADRANT_GATEWAY_NAME}-rlp
  namespace: ${KUADRANT_GATEWAY_NS}
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: ${KUADRANT_GATEWAY_NAME}
  defaults:
    limits:
      "low-limit":
        rates:
        - limit: 1
          window: 10s

    • A low-limit value is used in this example for the ease of testing the CR. Configure the spec.defaults.limits: values that makes in your use case.

  2. Apply your RateLimitPolicy CR by running the following command:

    $ oc apply -f <gateway_name-rlp.yaml>

    • Replace <gateway_name-rlp.yaml> with the name of your RateLimitPolicy YAML.

Verification

  1. Check that your RateLimitPolicy has Accepted and Enforced status by running the following command:

    $ oc get ratelimitpolicy ${KUADRANT_GATEWAY_NAME}-rlp -n ${KUADRANT_GATEWAY_NS} -o=jsonpath='{.status.conditions[?(@.type=="Accepted")].message}{"\n"}{.status.conditions[?(@.type=="Enforced")].message}'
    Example output
    RateLimitPolicy has been accepted
RateLimitPolicy has been successfully enforced

  2. Test your rate-limiting by running the following curl command:

    $ while :; do curl -k --write-out '%{http_code}\n' --silent --output /dev/null  "https://api.$KUADRANT_ZONE_ROOT_DOMAIN/cars" | grep -E --color "\b(429)\b|$"; sleep 1; done

    HTTP 403 responses are expected.

Add rate-limit headers to an API response

When you need to ensure that your traffic remains stable under heavy load, you can add rate-limit headers to your API responses.

By adding x-ratelimit-* headers, you can turn your APIs into self-documenting systems that can proactively throttle their own request frequency and time their retries. You can simplify debugging for developers and reduce unnecessary traffic spikes.

Prerequisites

  • You installed Connectivity Link on one or more clusters.

  • If you plan to use rate-limiting in a multicluster environment, you have a shared Redis-based datastore.

  • You installed the OpenShift CLI (oc).

  • You have write access to the OpenShift Container Platform namespaces you need to work with.

  • You have access to external or on-premise DNS.

  • You created a Gateway object.

  • You configured your gateway policies and HTTP routes.

  • You applied a default RateLimitPolicy CR to your deployment.

  • You have write access to the namespace where Connectivity Link is installed.

Procedure

  1. Find the name of the Limitador CR in your cluster by running the following command:

    $ oc get limitador -A

  2. Apply a patch to add headers to the CR by running the following command:

    $ oc patch limitador limitador -n KUADRANT-NAMESPACE --type=merge -p '{"spec": {"rateLimitHeaders": "DRAFT_VERSION_03"}}'
Verification

  • Test for the presence of headers by running the following command:

    $ curl -i -X GET http://<gateway_url>/path

    Replace <gateway_url> with the URL of your Gateway object.

    Example output
    HTTP/1.1 200 OK
x-ratelimit-limit: 5, 5;w=60
x-ratelimit-remaining: 4
x-ratelimit-reset: 58

↑ Up: Configure | ⌂ Home: Red Hat Connectivity Link | Next: On-premise DNS with CoreDNS →