Configuring the OCI Native Ingress Controller

Route requests based on host

You can configure the OCI native ingress controller to route an incoming request based on the domain name in the request's Host header (the host to which the request was originally sent).

To route a request to a particular backend service and port based on the host, create a route rule in the Ingress manifest. If the host matches the route rule, the OCI native ingress controller routes the request to the associated backend service and port.

For example, you might define the following rule to route requests originally sent to http://foo.bar.com to a backend service named ServiceA on port 80. All incoming traffic originally sent to http://foo.bar.com is routed to ServiceA on port 80.

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /
          backend:
            serviceName: ServiceA
            servicePort: 80

Route requests to different backend services based on path

You can configure the OCI native ingress controller to route incoming requests to different backend services, based on elements in the path to which the requests were originally sent.

To route a request to a particular backend service and port based on the path, create a route rule in the Ingress manifest. If the path matches the route rule, the OCI native ingress controller routes the request to the associated backend service and port. You can specify multiple paths in the same rule, to route requests to different backends.

For example, you might define the following rule to route requests based on the path to which the request was originally sent:

• If the path starts with /app1, the OCI native ingress controller routes the request to a backend service named ServiceA on port 80.
• If the path starts with /app2, the OCI native ingress controller routes the request to a backend service named ServiceB on port 443.

Since the rule does not specify a host, the rule applies to all incoming traffic.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443

Route requests based on host and path

You can configure the OCI native ingress controller to route an incoming request based on both the domain name in the request's Host header (the host to which the request was originally sent) and elements in the path to which the original request was sent.

To route a request to a particular backend service and port based on the host and path, create a route rule in the Ingress manifest. If the host and path match the route rule, the OCI native ingress controller routes the request to the associated backend service and port.

For example, you might define the following rule to route requests originally sent to http://foo.bar.com/app1 to a backend service named foo on port 80:

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: foo
            servicePort: 80

Route requests to a default backend

You can configure the OCI native ingress controller to route incoming requests to a default backend. You might configure a default backend to handle requests that do not match any route rules.

For example, you might define the following defaultBackend to route requests that do not match other rules in the Ingress manifest to a backend service named ServiceC on port 8080.

Note that if you do not specify any other rules in an Ingress manifest, you must specify a defaultBackend.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443
  defaultBackend:
    service:
      name: ServiceC
      port:
        number: 8080

Customizing general behavior using annotations

You can add annotations to the IngressClass or the Ingress resource manifests to customize general behavior of the OCI native ingress controller.

Customizing health check behavior using annotations

You can add annotations to the Ingress resource manifest to customize the health checks performed by the load balancer created by the OCI native ingress controller. For more information about load balancer health checks, see Health Checks for Load Balancers.

Option 1: OCI Native Ingress Controller obtains certificate from the Certificates service using a Kubernetes secret

To configure the OCI native ingress controller to obtain a certificate from the OCI Certificates service:

1. Obtain a TLS public and private key pair, and a certificate.

   In production environments, you obtain a TLS certificate from your chosen Certificate Authority by submitting a certificate signing request. During the certificate request process, a public key and corresponding private key are generated.

   In development and test environments, you can create a self-signed certificate and generate a private key yourself using a tool such as OpenSSL. For example (using OpenSSL 3.0 or later):

   1. Generate a public and private key pair by entering the following commands:

      openssl genrsa -out rootCA.key 4096

      openssl req -x509 -addext basicConstraints=critical,CA:TRUE -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt -subj /CN=RootCA

   2. Generate a certificate by entering the following commands:

      openssl genrsa -out server.key 4096

      openssl req -new -sha256 -key server.key -subj /C=US/ST=CA/O=MyOrg,Inc./CN=my.example.com -out server.csr

      openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out server.crt -days 500 -sha256

   In this example:

   • rootCA.key contains the key pair for the root CA.
   • rootCA.crt contains the root CA certificate.
   • server.key contains the key pair for generating the server certificate.
   • server.csr contains the certificate signing request for the server certificate.
   • server.crt contains the generated server certificate.
2. Create a Kubernetes secret resource in either of the following ways:

   • Using the kubectl create secret generic command, by entering:

     kubectl create secret generic <k8s-secret-name> --type=kubernetes.io/tls --from-file=ca.crt=<path-and-filename>.crt --from-file=tls.crt=<path-and-filename>.crt --from-file=tls.key=<path-and-filename>.key

     where:

     • <k8s-secret-name> is your choice of name for the Kubernetes secret
     • --from-file=ca.crt=<path-and-filename>.crt specifies the path to the file containing the root CA certificate. For example, --from-file=ca.crt=rootCA.crt
     • --from-file=tls.crt=<path-and-filename>.crt specifies the path to the file containing the generated server certificate. For example, --from-file=tls.crt=server.crt
     • --from-file=tls.key=<path-and-filename>.key specifies the path to the file containing the generated private key. For example, --from-file=tls.key=server.key

     For example:

     kubectl create secret generic example-tls-secret --type=kubernetes.io/tls --from-file=ca.crt=rootCA.crt --from-file=tls.crt=server.crt --from-file=tls.key=server.key

   • Using a Secret resource manifest file:

     1. Define the Kubernetes secret in a .yaml file, in the format:

        apiVersion: v1
        kind: Secret
        metadata:
          name: <k8s-secret-name>
        type: kubernetes.io/tls
        data:
          ca.crt: <base64-encoded-certificate-chain>
          tls.crt: <base64-encoded-server-certificate>
          tls.key: <base64-encoded-private-key>

        where:

        • name: <k8s-secret-name> is your choice of name for the Kubernetes secret resource.
        • ca.crt: <base64-encoded-certificate-chain> is the contents of the file (or files) containing intermediate certificates that form a certificate chain from the leaf certificate back to the Certificate Authority. Note that you can omit ca.cert, provided you include the entire certificate chain as the value of tls.cert (in which case, start the certificate chain with the contents of the file containing the generated server certificate, followed by the remaining certificates).
        • tls.crt: <base64-encoded-server-certificate> is the contents of the file containing the generated server certificate.
        • tls.key: <base64-encoded-private-key> is the contents of the file containing the generated private key.

        For example:

        apiVersion: v1
        kind: Secret
        metadata:
          name: example-tls-secret
        type: kubernetes.io/tls
        data:
          ca.crt : MIIFGERTegcDFRTuSDGfghREdE______Jre
          tls.crt: MIIC2DCCAcCgAwIBAgIBATANBg______kqh
          tls.key: MIIEpgIBAAKCAQEA7yn3bRHQ5F______HMQ

     2. Create the secret resource by entering kubectl create -f <filename>.yaml

3. Add the Kubernetes secret to an Ingress resource manifest:
   1. Define a new ingress resource in a .yaml file. See Create Ingress resource.
   2. In the spec: section of the manifest, add a tls: element that specifies both the host that is to receive HTTPS traffic and the name of the Kubernetes secret, in the format:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - <host-name>
          secretName: <k8s-secret-name>

      For example:

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret

   3. In the rules: section of the manifest, add a rule for the host that is to receive HTTPS traffic, and specify 443 as the port on which to listen for HTTPS traffic.

      For example:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-secret-ingress
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Create the resource by entering kubectl create -f <filename>.yaml

When you create the ingress resource, the OCI native ingress controller uses the Kubernetes secret to obtain a certificate of type Imported, and a CA bundle (Certificate Authority bundle), from the OCI Certificates service. The OCI native ingress controller associates the certificate with the listener, and the CA bundle with the backend set.

When the listener listening on port 443 receives an HTTPS request to the specified host, the listener uses the certificate for TLS termination. The listener then uses the routing rule to forward the request to the backend set. The backend set creates a new TLS connection with the backends running on the cluster (using the CA bundle as the trust authority for the new connection).

Option 2: You obtain certificate from the Certificates service

To configure the OCI native ingress controller to use a certificate that you have obtained from the OCI Certificates service:

1. Create a certificate in the OCI Certificates service in one of the following ways:
   • by importing a certificate issued by a third-party CA (the certificate will be of type Imported)
   • by issuing the certificate internally from a Certificates service CA (the certificate will be of type Issued by internal CA)

   Do not create a certificate to manage externally (of type Issued by internal CA, managed externally). For more information, see Creating a Certificate.

2. Make a note of the certificate's OCID.
3. Add the certificate's OCID to an Ingress resource manifest:
   1. Define a new ingress resource in a .yaml file. See Create Ingress resource.
   2. In the metadata: section, add an annotations: element that specifies the OCID of the certificate you created in the OCI Certificates service, in the format:

      kind: Ingress
      metadata:
        name: <i-name>
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid>
      spec:
      ...

      where:

      • name: <i-name> is your choice of name for the ingress resource.
      • oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid> is the OCID of the certificate you created in the OCI Certificates service

      For example:

      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
      ...

   3. In the rules: section of the Ingress resource manifest, add a rule for the host that is to receive HTTPS traffic, and specify 443 as the port on which to listen for HTTPS traffic.

      For example:

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Create the resource by entering kubectl create -f <filename>.yaml

What happens when you create the ingress resource depends on how you created the certificate in the OCI Certificates service:

• If you created the certificate by importing a certificate issued by a third-party CA, the certificate is of type Imported. The OCI native ingress controller associates the certificate with the listener, creates a CA bundle from the certificate chain, and associates the CA bundle with the backend set. Note that you cannot configure certificates of type Imported to be automatically rotated.
• If you created the certificate by issuing the certificate internally from a Certificates service CA, the certificate is of type Issued by internal CA. The OCI native ingress controller associates the certificate with the listener, obtains the OCID of the CA, and associates that OCID with the backend set. Note that you can configure certificates of type Issued by internal CA to be automatically rotated.

When the listener listening on port 443 receives an HTTPS request to the specified host, the listener uses the certificate for TLS termination. The listener then uses the routing rule to forward the request to the backend set. The backend set creates a new TLS connection with the backends running on the cluster (using the CA bundle, or the CA identified by its OCID, as the trust authority for the new connection).

Applying defined tags to the load balancer

Defined tags are set up and managed by a tag administrator. A defined tag consists of a tag namespace, a key, and a value. The tag namespace and tag key definition must be set up in a tenancy before you can apply a defined tag to a resource.

To specify that the OCI native ingress controller is to apply defined tags to the load balancer, use the oci-native-ingress.oraclecloud.com/defined-tags annotation in the IngressClass manifest, in the following format:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'
spec:
  ...

where:

• <tag-namespace> is the tag namespace to which the tag belongs.
• <tag-key> is the name of a defined tag to apply to the load balancer.
• <tag-value> is either a value for the tag from a pre-defined list of values, or a new value, or blank (depending on how the defined tag has been set up).

The value of the oci-native-ingress.oraclecloud.com/defined-tags annotation is a JSON string, enabling you to specify multiple tag namespaces, tag keys, and tag values in JSON format.

For example:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"Operations": {"CostCenter": "42", "Department": "001"}, "Sales": {"Region": "US"}}'
spec:
  ...

Changing one of the tags in the oci-native-ingress.oraclecloud.com/defined-tags annotation of the IngressClass manifest causes the OCI native ingress controller to reapply to the load balancer all of the defined tags specified by the annotation. However, if a defined tag contains a tag variable, the OCI native ingress controller only reapplies the defined tag to the load balancer if the tag is not already present.

Note that to enable the OCI native ingress controller to apply defined tags to a load balancer, a suitable IAM policy must exist to enable the OCI native ingress controller to use the appropriate tag namespace. For more information, see:

• Granting Permissions to the OCI Native Ingress Controller as a Standalone Program
• Granting Permissions to the OCI Native Ingress Controller Cluster Add-on

Applying free-form tags to the load balancer

Free-form tags are not managed by a tag administrator. A free-form tag consists of a key and a value. Unlike defined tags, free-form tags do not belong to a tag namespace.

To specify that the OCI native ingress controller is to apply free-form tags to the load balancer, use the oci-native-ingress.oraclecloud.com/freeform-tags annotation in the IngressClass manifest, in the following format:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"<tag-key>": "<tag-value>"}'
spec:
  ...

where:

• <tag-key> is a name for the free-form tag to apply to the load balancer.
• <tag-value> is a value for the free-form tag to apply to the load balancer.

The value of the oci-native-ingress.oraclecloud.com/freeform-tags annotation is a JSON string, enabling you to specify multiple tag keys and tag values in JSON format.

For example:

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"Project": "Red", "Version": "Alpha"}'
spec:
  ...

Changing one of the tags in the oci-native-ingress.oraclecloud.com/freeform-tags annotation of the IngressClass manifest causes the OCI native ingress controller to reapply to the load balancer all of the free-form tags specified by the annotation.

Applying tag defaults to the load balancer

Tag defaults are set up for a specific compartment. Tag defaults are compartment-specific. Tag defaults specify defined tags that are applied automatically to all resources created in a specific compartment at the time of creation.

When using the OCI native ingress controller version 1.4.0 (or later), tag defaults are automatically applied to load balancers that the OCI native ingress controller creates. Subsequently, the OCI native ingress controller retains a tag default applied to a load balancer unless one of the following conditions is met:

• You manually remove a tag default that has been automatically applied to a load balancer.
• You specify a tag default as a defined tag, using the oci-native-ingress.oraclecloud.com/defined-tags annotation (in which case, the OCI native ingress controller treats the tag default as any other defined tag).

Note that tag defaults with user-applied values are not supported. If a tag default with a user-applied value has been set up for a compartment in which the OCI native ingress controller is to create or manage a load balancer, you must use the oci-native-ingress.oraclecloud.com/defined-tags annotation to specify the tag default as a defined tag.

For load balancers created using an OCI native ingress controller version earlier than version 1.4.0, or when using the oci-native-ingress.oraclecloud.com/id annotation to specify that the OCI native ingress controller is to manage an existing load balancer, note that tag defaults are not supported. In both cases, to apply or retain a tag default, use the oci-native-ingress.oraclecloud.com/defined-tags annotation to specify the tag default as a defined tag instead.