Oracle Cloud Infrastructure Documentation

Creating a Virtual Service

Create a virtual service for a service mesh.

Important

Before you proceed, you must set up the appropriate OCI policies for the virtual service resource. For details, Required IAM Policy for Virtual Services.
    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 a virtual service.
    5. On the details page of the mesh, under the Virtual Services table, click Create virtual service.
    6. In the Create Virtual Service panel, provide the following details:
      • Name : The name of the virtual service. The name must be unique within the same service mesh and can't be changed after creation (immutable). 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 virtual service. Avoid entering confidential information.
      • Compartment: The compartment in which you want to create the virtual service. The default compartment is the one you selected before, but you can select any compartment that you have permission to work in.
      • Default Routing Policy: (Optional)The default routing policy across virtual deployments within a virtual service. If no virtual service route tables are present, the virtual service applies the default routing policy.

        The routing options are as follows:

        • Uniform: Distributes traffic uniformly across virtual deployments.
        • Deny: The default option. Disables routing. Sends no traffic to the virtual deployments.

        For more information, see Routing Traffic in a Virtual Service.

      • mTLS Mode: (Optional) The mTLS authentication mode to use when receiving requests from other virtual services or ingress gateways within the mesh. Select the level of security.
        • Disabled: Accept raw TCP traffic. No minimum virtual services within this mesh can use any mTLS authentication mode.
        • Permissive: Accept both mTLS and raw TCP traffic. Virtual services within this mesh use either the Permissive or Strict mode.
        • Strict: Accept mTLS traffic. All virtual services within this mesh must use Strict mode.

        For more information on using mTLS on Service Mesh, see Using mTLS with Service Mesh.

      • Certificate Maximum Validity (Days): Set the maximum validity of the certificates while creating virtual services.
        Note

        The maximum validity can range from a minimum of 45 days to a maximum of 90 days. The default value is 45 days.
      • Hosts: (Optional) The DNS host names of the virtual service used by its callers. Supports wild card host names in prefix form. Specify up to 10 DNS host names. The following are examples of valid host names: www.example.com, *.example.com, *.com, www.example.com:9080, *.example.com:9080. Can be omitted if the virtual service only has TCP virtual deployments.
        Warning

        Don't use the following service mesh reserved ports in this resource: 15000, 15003, 15006, and 9901.

        For services with HTTP based virtual deployments, the host name must match the HTTP host header used to communicate with the service. If a mismatch occurs, the applications connecting to this service receives 404 errors. The HTTP host header is of the form example.com for standard ports 80 and 443. For a nonstandard port such as 9080, the host header is of the form example.com:9080.

        For services with virtual deployments based on TLS_PASSTHROUGH, the host name must match the server name indication (SNI) used to communicate with the service. If a mismatch occurs, the applications connecting to this service receives TLS handshake errors. The service allows wild cards in the prefix form but doesn't allow a blanket wild card: *.

        SNI is similar to HTTP host headers but for TLS. However, port information isn't required for SNI. For example, if you're running a Kubernetes service on SNI example.com and on a nonstandard port 9080, you must define example.com as a host on the virtual service.

        Important

        Hosts entries aren't required for egress-only services. Egress-only services are microservices that don't receive any calls from other services.

        To add more hosts, click + Add another host.

      • + Add another virtual deployment: The button adds virtual deployment to this virtual service.

        For more information about virtual deployments, see Managing Virtual Deployments.

      • + Add another route table: Add a routing table to this virtual service.

        For more information about route tables, see Managing Virtual Service Route Tables.

    7. (Optional) To add tags to the virtual service, click show advanced options. For more information about tagging, see Resource Tags.
    8. Click Create virtual service.

  • To see what operations are available for virtual-service create use:

    oci service-mesh virtual-service create -h

    To create a virtual service using the CLI, run oci service-mesh virtual-service create to create the virtual service:

    oci service-mesh virtual-service create --name "<name>" --compartment-id <compartmentId> --description <description> --mesh-id <meshId> --default-routing-policy <defaultRoutingPolicy> --hosts  <hosts> --mtls <mtls>

    Where:

    • <name>: The name of the virtual service. The name must be unique within the same service mesh and can't be changed after creation (immutable). 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 virtual service belongs.
    • <meshId>: The OCID of the service mesh in which this virtual service is created.
    • <description>: (Optional) The description of the virtual service. Avoid entering confidential information.
    • <defaultRoutingPolicy>: The default routing policy across virtual deployments within a virtual service. If no virtual service route tables are present, the virtual service applies the default routing policy. Options are DENY or UNIFORM. The default routing policy is DENY. Specify the parameter with a key of type and value of the selected routing option. The parameter must be in valid JSON format (either as a string, or passed in as a file using the file:///<filename> syntax including a path).

      The routing options are as follows:

      • Uniform: Distributes traffic uniformly across virtual deployments.
      • Deny: The default option. Disables routing. Sends no traffic to the virtual deployments.

      For more information, see Routing Traffic in a Virtual Service.

    • <hosts>The DNS host names of the virtual service used by its callers. Supports wild card host names in prefix form. Specify up to 10 DNS host names. The following are examples of valid host names: www.example.com, *.example.com, *.com, www.example.com:9080, *.example.com:9080. Can be omitted if the virtual service only has TCP virtual deployments. The value for <hosts> must be in valid JSON format (either as a string, or passed in as a file using the file:///<filename> syntax including a path).
      Warning

      Don't use the following service mesh reserved ports in this resource: 15000, 15003, 15006, and 9901.

      For services with HTTP based virtual deployments, the host name must match the HTTP host header used to communicate with the service. If a mismatch occurs, the applications connecting to this service receives 404 errors. The HTTP host header is of the form example.com for standard ports 80 and 443. For a nonstandard port such as 9080, the host header is of the form example.com:9080.

      For services with virtual deployments based on TLS_PASSTHROUGH, the host name must match the server name indication (SNI) used to communicate with the service. If a mismatch occurs, the applications connecting to this service receives TLS handshake errors. The service allows wild cards in the prefix form but doesn't allow a blanket wild card: *.

      SNI is similar to HTTP host headers but for TLS. However, port information isn't required for SNI. For example, if you're running a Kubernetes service on SNI example.com and on a nonstandard port 9080, you must define example.com as a host on the virtual service.

      Important

      Hosts entries aren't required for egress-only services. Egress-only services are microservices that don't receive any calls from other services.
    • <mtls>The mTLS authentication mode to use when receiving requests from other virtual services or ingress gateways within the mesh. Set mTLS <mode> to DISABLED, PERMISSIVE, or STRICT as described in the following list. Additionally, specify <maximumValidity> to determine the number of days the mTLS certificate is valid for. Specify a value between 45 and 90. The default value is 45 days. The value of <mtls> must be in valid JSON format (either as a string, or passed in as a file using the file:///<filename> syntax including a path).
      • <mode>:
        • Disabled: Accept raw TCP traffic. No minimum virtual services within this mesh can use any mTLS authentication mode.
        • Permissive: Accept both mTLS and raw TCP traffic. Virtual services within this mesh are either PERMISSIVE or STRICT modes.
        • Strict: Accept mTLS traffic. All virtual services within this mesh must use STRICT mode.

        For more information on using mTLS on Service Mesh, see Using mTLS with Service Mesh.

    For example:

    oci service-mesh virtual-service create --compartment-id ocid1.compartment.oc1..aaa... --mesh-id ocid1.mesh.oc1..aaa... --name "my virtual-service" --description "virtual-service description" --default-routing-policy '{"type":"UNIFORM"}' --hosts '["www.example.com"]' --mtls '{"maximum-validity":45,"mode":"STRICT"}'

    The response to the command includes:

    • The virtual service's OCID.
    • The life cycle state (for example, ACTIVE, FAILED).
    • The ID of the work request to create the virtual service (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 virtual service 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 virtual-service create --compartment-id ocid1.compartment.oc1..aaa... --mesh-id ocid1.mesh.oc1..aaa... --name "my virtual-service" --description "virtual-service description" --default-routing-policy '{"type":"UNIFORM"}' --hosts '["www.example.com"]' --mtls '{"maximum-validity":45,"mode":"STRICT"}' --wait-for-state SUCCEEDED
    Tip

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

    Checking Virtual Service Status

    To see the status of the virtual service, enter:

    oci service-mesh virtual-service get --virtual-service-id <virtualServiceId>

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

    Creating a Virtual Service using JSON File

    Alternatively, create a virtual service by supplying a JSON file to the create command.

    1. Generate a sample JSON file for a virtual service:

      oci service-mesh virtual-service 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 virtual-service create command: 

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

    For more information about using the CLI, see:

  • Use the CreateVirtualService operation to create a virtual service.