Managing Ingress Gateways with kubectl

Required IAM Policy for Ingress Gateways

To use an ingress gateway, an administrator must grant you the required type of access in a policy (IAM). Whether you're using the Console, the REST API with an SDK, the CLI, Kubernetes kubectl, or other tool, the correct permissions are required.

Allow group MeshAdmins to manage mesh-ingress-gateways in compartment sales-app

View Kubernetes Configuration Options for Ingress Gateways

You can view the Kubernetes CLI ingress gateway YAML configuration options by displaying the Custom Resource Definition (CRD). Use the following command:

kubectl get crd ingressgateways.servicemesh.oci.oracle.com -o yaml

In the CRD, you see the fields used in a YAML configuration file under spec:schema:openAPIV3Schema:properties:spec. CRD output also includes information about field types, ranges, and limits. The following section provides an example of a YAML configuration file.

Creating an Ingress Gateway

To create an ingress gateway, use the kubectl apply command. For example:

kubectl apply -f ingress-gateway.yaml

Resources can be created in different namespaces by specifying the metadata:namespace field in the YAML configuration file. By default, if namespace is not provided, service mesh uses the current namespace. When specifying the mesh in the spec section of the YAML configuration file, you can either use the mesh reference or mesh ID.

apiVersion: servicemesh.oci.oracle.com/v1beta1
kind: IngressGateway
metadata:
  name: <sample-ingress-gateway>    # Name of Ingress Gateway
  namespace: <sample-namespace>
spec:
  compartmentId: ocid1.compartment.oc1..aaa...
  name: <sample-ig>     # Ingress Gateway name inside the mesh
  description: This Ingress Gateway
  mesh:
    ref:
      name: <sample-mesh>
      namespace: <sample-mesh-namespace>  # Namespace of the referenced CR. If unspecified, defaults to the referencing object's namespace.
  hosts:
    - name: samplehost
      hostnames:
        - samplehost.example.com
        - www.samplehost.example.com
      listeners:
        - port: 8080
          protocol: HTTP
          tls:
            mode: MUTUAL_TLS
            serverCertificate:
              ociTlsCertificate:
                certificateId: ocid1.certificate.oc1..aaa...
            clientValidation:
              trustedCaBundle:
                ociCaBundle:
                  caBundleId: ocid1.caBundle.oc1..aaa...
              subjectAlternateNames:
                - authorized1.client
                - authorized2.client
        - port: 9090
          protocol: HTTP
          tls:
            mode: TLS
            serverCertificate:
              kubeSecretTlsCertificate:
                secretName: sampleCertSecretName
  accessLogging:
    isEnabled: true

apiVersion: servicemesh.oci.oracle.com/v1beta1
kind: IngressGateway
metadata:
  name: <sample-ingress-gateway>    # Name of Ingress Gateway
  namespace: <sample-namespace>
spec:
  compartmentId: ocid1.compartment.oc1..aaa...
  name: <sample-ig>     # Ingress Gateway name inside the mesh
  description: This Ingress Gateway
  mesh:
    id: ocid1.mesh.oc1...aa...
  hosts:
    - name: samplehost
      hostnames:
        - samplehost.example.com
        - www.samplehost.example.com
      listeners:
        - port: 8080
          protocol: HTTP
          tls:
            mode: MUTUAL_TLS
            serverCertificate:
              ociTlsCertificate:
                certificateId: ocid1.certificate.oc1..aaa...
            clientValidation:
              trustedCaBundle:
                ociCaBundle:
                  caBundleId: ocid1.caBundle.oc1..aaa...
              subjectAlternateNames:
                - authorized1.client
                - authorized2.client
        - port: 9090
          protocol: HTTP
          tls:
            mode: TLS
            serverCertificate:
              kubeSecretTlsCertificate:
                secretName: sampleCertSecretName
  accessLogging:
    isEnabled: true

Where:

• <name>The name of the ingress gateway. The name must be unique within the same service mesh and can't be changed after creation. The name must start with a letter or underscore, followed by letters, numbers, hyphens, or underscores. Length can be 1–255 characters. Avoid entering confidential information.
• <compartmentId>: The OCID of the compartment to which the ingress gateway belongs.
• <mesh:id:> The OCID of the service mesh in which this internet gateway is created.
• <hosts>: An array of hostnames and their listener configuration that this gateway binds to.
  • <name>: A user-friendly name for the host. The name must be unique across ingress gateways within a mesh. This name can be used in the ingress gateway route table resource to attach a route to this host.
  • <hostnames>:
    The DNS host names used by callers of the gateway. Wildcard host names are supported in the prefix form. Specify up to 10 DNS host names for this gateway. The following examples are valid host names: www.example.com, *.example.com, *.com, www.example.com:9080, *.example.com:9080

    Caution
    
    Don't use the following Service Mesh reserved ports in your mesh resource: 15000, 15003, 15006, and 9901.

    For hosts with an HTTP listener, the host name must match the HTTP host header used to communicate with the gateway. If a mismatch occurs, the users connecting to this gateway notices 404 errors. The HTTP host header uses the form example.com for standard ports 80 and 443. For a nonstandard port like 9080, the host header uses the form example.com:9080.

    For hosts with a listener TLS_PASSTHROUGH, the host name must match the server name indication (SNI) used to communicate with the gateway. If a mismatch occurs, the users connecting to this gateway notices TLS handshake errors. Wildcards in the prefix form are allowed. A blanket wildcard * isn't allowed.
• <listeners>:
  • <port>: Specify the port to listen on.
  • <protocol>: Select the protocol: HTTP, TCP, or TLS_PASSTHROUGH. If TLS_PASSTHROUGH is selected, the proxy does not manage TLS. Encrypted data is passed "as is" to the application which manages TLS on its own.
  • <tls>:
    • <mode>: Select from:
      • Mutual TLS: Only mTLS traffic is accepted. Functions like STRICT for meshes and virtual services.
      • Permissive: Connection can be either plain text or TLS/mTLS. When the TLS client validation section is configured for the listener, mTLS is performed and the gateway validates the client's certificates. For the TLS client validation section, see the next section in the form.
      • TLS: Allows one-way TLS authentication. Only clients connecting to the gateway verify the gateway's identity.
      • Disabled: Raw TCP traffic is accepted.
    • <serviceCertificate>
      • <certificateId>: The OCID of the TLS certificate.
      • <secretName>: Put the secret value in this field.
    • <clientValidation>:
      • <trustedCaBundle >:
        • <ociCaBundle:caBundleId>: The OCID of the CA bundle.
      • <subjectAlternateNames>: Enter domain names here. For example: example.com, servicemesh.example.com.

Updating an Ingress Gateway

To update an ingress gateway with kubectl:

1. Change the existing YAML configuration file for the ingress gateway as needed.
2. Save the file.
3. Run the apply command again.

   kubectl apply -f ingress-gateway.yaml

Moving an Ingress Gateway

To move an ingress gateway to a different compartment:

1. Update the compartment OCID to the value of the target compartment in the existing YAML configuration file for the ingress gateway.
2. Save the file.
3. Run the apply command again.

   kubectl apply -f ingress-gateway.yaml

Getting a List of Ingress Gateways

To get a list of ingress gateways in a namespace, use the following command:

kubectl get ingressgateways -n <namespace>

Getting Ingress Gateway Details

To view the details of a specific ingress gateway in a namespace, use the following command:

kubectl describe ingressgateway <name> -n <namespace>

Deleting an Ingress Gateway

To delete of a specific ingress gateway in a namespace, use the following command:

kubectl delete ingressgateway <name> -n <namespace>