Oracle Cloud Infrastructure Documentation

Creating an Ingress Gateway

Create an ingress gateway for a service mesh.

Important

Before you proceed, you must set up the appropriate OCI policies for the ingress gateway resource. For details, see Required IAM Policy for Ingress Gateways.
    1. Open the navigation menu and click Developer Services. Under Containers & Artifacts, click Service Mesh.
    2. Click Service Meshes.
    3. On the Service Mesh page, from the list of compartments on the left side, select a compartment.
    4. From the list of meshes, click the mesh name for which you want to create an ingress gateway.
    5. On the details page of the mesh, under Resources, click Ingress Gateways.
    6. In the Ingress Gateways table, click Create ingress gateway.
    7. In the Create Ingress Gateway panel, provide the following details at the top of the panel:
      • 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.
      • Description: (Optional) The description of the ingress gateway. The description can be changed after creation. Avoid entering confidential information.
      • Certificate Maximum Validity (Days): Set the maximum validity of the certificates while creating ingress gateways.
        Note

        Maximum validity can range from a minimum of 45 days to a maximum of 90 days.
      • Compartment: The compartment in which you want to create the ingress gateway. The default compartment is the one you selected before, but you can select any compartment that you have permission to work in.
      • Enable access logs: Select the check box to enable access logs.
    8. In the Host section, provide the following details:
      • 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.
      • Host name:
        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.

        To add another name, click + Add another name.

    9. In the Listener section, provide the following details:
      • Port: Specify the port to listen on.
      • Protocol: Select HTTP, TCP, or TLS_PASSTHROUGH. If you select TLS_PASSTHROUGH, the proxy doesn't manage TLS. Encrypted data is passed as is to the application which manages TLS on its own.
      • TLS Mode: Select one of the following options:
        • 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.
      • TLS client validation: In this section, provide the following details:
        • Subject alternate names: Enter a domain name such as example.com, servicemesh.example.com. To add another name, click + Add another name.
        • Type: For the type of CA bundle, select OCI Certificates or Local File.
        • CA Bundle in <compartment>: If you select OCI Certificates as the type of CA bundle, the CAs in the compartment are listed.
        • Secret name: If you select Local File as the type of CA bundle, enter the name of the Kubernetes secret of type TLS.
        • TLS server certificate: In this section, provide the following details:
          • Type: Select OCI Certificates or Local File.
          • Certificate in <compartment>: If you select OCI Certificates as the type, this lists associate IDs to the certificates in the CA. Select different certificates using the available IDs.
          • Secret Name: If you select Local File as the type, enter the file name of an opaque Kubernetes secret with a key of ca.crt.
        • To add another listener, click +Add additional listener.
    10. To add another host, click + Add another host.
    11. To add an ingress gateway route table, click + Add another route table.
    12. (Optional) To add tags to the ingress gateway, click show advanced options. For more information about tagging, see Resource Tags.
    13. Click Create ingress gateway.

  • To see what operations are available for ingress-gateway create use:

    oci service-mesh ingress-gateway create -h

    To create an ingress gateway using the CLI, run oci service-mesh ingress-gateway create to create the ingress-gateway:

    oci service-mesh ingress-gateway create --name <name> --compartment-id <compartmentId> --mesh-id <meshId> --hosts <hosts> --access-logging <accessLogging> --description <description>

    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.
    • <meshId>: The OCID of the service mesh in which this internet gateway is created.
    • <hosts>: An array of host names 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.
          • <clientValidation>:
            • <subjectAlternateNames>: Enter domain names here. For example: example.com, servicemesh.example.com.
            • <trustedCaBundle >:
              • <type>: Possible values are OCI_CERTIFICATES or LOCAL_FILE.
              • <caBundleId>: The OCID of the CA bundle.
              • <secretName>: If LOCAL_FILE is selected, the file name of a Kubernetes secret of type TLS. Put the name of the secret in this field.
          • <serviceCertificate>
            • <type>: Possible values are OCI_CERTIFICATES or LOCAL_FILE.
            • <certificateId>: If OCI_CERTIFICATES is specified, the OCID of the TLS certificate.
            • <secretName>: If LOCAL_FILE is selected, the file name of an opaque Kubernetes secret with a key of ca.crt. Put the name of the secret in this field.

      This is a complex type whose value must be valid JSON. We recommend storing the YAML example in a file, then modifying the file as needed to make updates. See the following section for details on getting the JSON values: Creating an Ingress Gateway using a JSON File.

    • <accessLogging>: Turn logging on or off by setting the value to true or false. This is a complex type whose value must be valid JSON. See the following section for details on getting the JSON values: Creating an Ingress Gateway using a JSON File.
    • <description>The description of the ingress gateway. The description can be changed after creation. Avoid entering confidential information.

    For example:

    oci service-mesh ingress-gateway create --name "ingress gateway" --compartment-id ocid1.compartment.oc1..aaa... --mesh-id ocid1.mesh.oc1..aaa... --hosts '[{ "hostnames": ["test.com"], "listeners": [{"port": 8080, "protocol": "HTTP", "tls": {"clientValidation": {"subjectAlternateNames": ["authorized1.client"], "trustedCaBundle": [{"caBundleId": "ocid1.caBundle.oc1..aaa...", "type": "OCI_CERTIFICATES"}]}, "mode": "MUTUAL_TLS", "serverCertificate": [{"certificateId": "ocid1.certificate.oc1..aaa...", "type": "OCI_CERTIFICATES"}]}}]'

    The response to the command includes:

    • The ingress gateway's OCID.
    • The life cycle state (for example, ACTIVE, FAILED).
    • The ID of the work request to create the ingress gateway (details of work requests are available for seven days after completion, cancellation, or failure).

    If you want the command to wait to return control until the ingress gateway is active or the request has failed, include either or both of the following parameters:

    • --wait-for-state SUCCEEDED
    • --wait-for-state FAILED

    For example:

    oci service-mesh ingress-gateway create --name "ingress gateway" --compartment-id ocid1.compartment.oc1..aaaaaaaasbdlq2go7wwxlk6g2sjiiamouh4zarpe5zpewhbv333sekhfnkka --mesh-id ocid1.mesh.oc1.iad.amaaaaaafesvpoaauhikwwofwuali3f3lgmfikqwdgosr22hj3pznak6qrvq --hosts file:///ig_hosts.json --wait-for-state SUCCEEDED
    Tip

    You can't use the ingress gateway until the work request has successfully created it and the ingress gateway is active.

    Checking Ingress Gateway Status

    To see the status of the ingress gateway, enter:

    oci service-mesh ingress-gateway get --ingress-gateway-id <ingressGatewayId>

    To view the status of the work request creating the ingress gateway, refer to Service Mesh Work Requests.

    Creating an Ingress Gateway using a JSON File

    Alternatively, create an ingress gateway by supplying a JSON file to the create command.

    1. Generate a sample JSON file for an ingress gateway:

      oci service-mesh ingress-gateway create --generate-full-command-json-input
    2. Create a JSON file with the sample-generated output from preceding step and update the fields with appropriate values.

    3. Supply the JSON file to the ingress-gateway create command: 

      oci service-mesh ingress-gateway create --from-json file:///<filename>

    For more information about using the CLI, see:

  • Use the CreateIngressGateway operation to create an ingress gateway.