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).