Managing Virtual Services with kubectl

With the kubectl command you can create, update, move, list, view, and delete a virtual service. The following topics detail how to manage these operations with kubectl.

Required IAM Policy for Virtual Services

To use a virtual service, 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.

When an action produces a permission denied or unauthorized message, confirm a couple of settings with your administrator. The administrator must ensure that the correct type of access is granted and the correct compartment is specified.

For example, to allow users in the group MeshAdmins to create, update, and delete all virtual services in the compartment sales-app:

Allow group MeshAdmins to manage mesh-virtual-services in compartment sales-app

For Service Mesh IAM policy reference details for each resource, see: Service Mesh IAM Policies.

For a step-by-step guide to set up all the required IAM policies for a Service Mesh, see: Set up Policies required for Service Mesh

Creating a Virtual Service

To create a virtual service, use the kubectl apply command. For example:

kubectl apply -f virtual-service.yaml

Create resources in different namespaces by specifying the metadata:namespace field in the YAML configuration file. By default, if namespace isn't provided, the command uses the current namespace. When specifying the mesh in the spec section of the YAML configuration file, you use either the mesh ID or the mesh reference.

Sample: virtual-service.yaml (Reference)

apiVersion: servicemesh.oci.oracle.com/v1beta1
kind: VirtualService
metadata:
name: <virtualServiceName>  # Name of virtual service
  namespace: <k8sAppNamespace>
  labels:
    version: v1
spec:
  compartmentId: ocid1.compartment.oc1..aaa...
  name: <virtualServiceName>  # Virtual service name inside the mesh
  description: <description>
  mesh:
    ref:
      name: <meshName>  # Name of the containing mesh resource.
      namespace: <sample-mesh-namespace>  # Namespace of the referenced custom resource.
  defaultRoutingPolicy:
    type: UNIFORM
  hosts:
    - <vsHostName>.example.com  # Host name matching vs-name. 
  mtls:
    maximumValidity: 45  # Default is 45. 
    mode: STRICT

Sample: virtual-service.yaml (ID)

apiVersion: servicemesh.oci.oracle.com/v1beta1
kind: VirtualService
metadata:
  name: <virtualServiceName>  # Name of virtual service
  namespace: <k8sAppNamespace>
  labels:
    version: v1
spec:
  compartmentId: ocid1.compartment.oc1..aaa...
  name: <virtualServiceName>  # Virtual service name inside the mesh
  description: <description>
  mesh:
    id: ocid1.mesh.oc1..aa...
  defaultRoutingPolicy:
    type: UNIFORM
  hosts:
    - <vsHostName>.example.com  # Host name matching vs-name.
  mtls:
    maximumValidity: 45  # Default is 45.
    mode: STRICT

Tip

Refer to Service Mesh Kubernetes Resource Conditions for details on Service Mesh Kubernetes custom resource statuses.

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

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.
- <mode>:
  - DISABLED: Accept raw TCP traffic. No minimum virtual services or ingress gateways within this mesh can use any mTLS authentication mode.
  - PERMISSIVE: Accept both mTLS and raw TCP traffic. Virtual services and ingress gateways within this mesh are either PERMISSIVE or STRICT modes.
  - STRICT: Accept mTLS traffic. All virtual services and ingress within this mesh must use STRICT mode.
  For more information on using mTLS on Service Mesh, see Using mTLS with Service Mesh.

Updating a Virtual Service

To update a virtual service with kubectl:

Change the existing YAML configuration file for the virtual service as needed.
Save the file.
Run the apply command again:
```
kubectl apply -f virtual-service.yaml
```

Moving a Virtual Service

To move a virtual service to a different compartment:

Update the compartment OCID to the value of the target compartment in the existing YAML configuration file for the virtual service.
Save the file.
Run the apply command again:
```
kubectl apply -f virtual-service.yaml
```

Get a List of Virtual Services

To get a list of virtual services in the namespace, use the following command:

kubectl get virtualservices -n <namespace>

Getting Virtual Service Details

To view the details of a specific virtual service in the namespace, use the following command:

kubectl describe virtualservice <name> -n <namespace>

Delete a Virtual Service

To delete of a specific virtual service in the namespace, use the following command:

kubectl delete virtualservice <name> -n <namespace>

Note

If any child resources exist in the virtual service, for example virtual deployments or virtual service route tables, the delete operation fails.

Oracle Cloud Infrastructure Documentation