Updating an Ingress Gateway

Update the description, certificate validity, or log settings of an ingress gateway in 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, which contains the ingress gateway that you want to update.
    5. On the details page of the mesh, under Resources, click Ingress Gateways.
    6. In the Ingress Gateways table, click the ingress gateway that you want to update.
    7. On the details page of the ingress gateway, click Edit.
    8. In the Edit Ingress Gateway panel, update the details as required. You can update the description, certificate maximum validity, and log settings of the gateway.
    9. Click Save changes.
  • To see what operations are available for ingress-gateway update use:

    oci service-mesh ingress-gateway update -h

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

    oci service-mesh ingress-gateway update --ingress-gateway-id <ingressGatewayId> --access-logging <accessLogging> --description <description> --hosts <hosts>

    Where:

    • <ingressGatewayId>: The OCID of the ingress gateway to move. To find out the Ingress Gateway's OCID, see Listing Ingress Gateways.
    • <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.
    • <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 JSON 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.

    For example:

    oci service-mesh ingress-gateway update --ingress-gateway-id ocid.meshingressgateway.oc1.iad.aaaa.... --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 update 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 update --ingress-gateway-id ocid.meshingressgateway.oc1.iad.aaaa.... --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"}]}}]' --wait-for-state SUCCEEDED
    Tip

    You can't use the ingress gateway until the work request has successfully updated 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 updating the ingress gateway, refer to Service Mesh Work Requests.

    Updating an ingress gateway using a JSON File

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

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

      oci service-mesh ingress-gateway update --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 update command:

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

    For more information about using the CLI, see:

  • Use the UpdateIngressGateway operation to update an ingress gateway.