use kubectl to connect to an ASM instance - Alibaba Cloud Service Mesh

To manage Istio resources such as VirtualService, DestinationRule, and Gateway definitions from the command line, connect a kubectl client to your Service Mesh (ASM) instance. After you connect, you can create, update, and delete Istio resources on the ASM control plane the same way you manage resources on any Kubernetes cluster.

How it works

kubectl is a command-line tool of Kubernetes. You can use kubectl to manage Kubernetes clusters, containerized applications deployed in Kubernetes clusters, and ASM instances.

ASM exposes a Kubernetes-compatible API server on its control plane. Save a kubeconfig file from the ASM console to your local machine and point kubectl at this API server. kubectl then communicates with the ASM control plane through standard Kubernetes API calls.

Based on the Kubernetes role-based access control (RBAC) mode, ASM includes a predefined ClusterRole named istio-admin. You can assign roles with the following permissions to users as required:

Scope	Resources	Allowed operations
Namespaces	`namespaces`	create, delete, get, list, patch, update, watch
Istio resources	All resources in `config.istio.io`, `networking.istio.io`, `authentication.istio.io`, `rbac.istio.io`, `security.istio.io`	create, delete, get, list, patch, update, watch
Ingress gateways	`istiogateways.istio.alibabacloud.com`	create, delete, get, list, patch, update, watch
Alibaba Cloud Istio extensions	All resources in `istio.alibabacloud.com`	get, list (read-only)

Full ClusterRole YAML

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: istio-admin
rules:
- apiGroups: [""]
  resources: ["namespaces"]
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - config.istio.io
  - networking.istio.io
  - authentication.istio.io
  - rbac.istio.io
  - security.istio.io
  resources: ["*"]
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - istio.alibabacloud.com
  resources: ["istiogateways"]
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - istio.alibabacloud.com
  resources: ["*"]
  verbs:
  - get
  - list

Prerequisites

Before you begin, make sure that you have:

An ASM instance
kubectl installed on your local machine. You can download a version of kubectl from GitHub. For installation instructions, see Install and Set Up kubectl.
(Internet access only) An elastic IP address (EIP) associated with the API server of the ASM instance. Without an EIP, the Internet Access tab does not appear in the Connection panel. Use Internal Access instead.

Verify your kubectl installation:

kubectl version --client

Step 1: Copy the kubeconfig file

Log on to the ASM console.
In the left-side navigation pane, choose Service Mesh > Mesh Management.
On the Mesh Management page, click the name of the target ASM instance.
In the left-side navigation pane, choose ASM Instance > Base Information.
In the upper-right corner of the Base Information page, click Connection.
In the Connection panel, click the Internet Access or Internal Access tab depending on how your network connects to the ASM instance.
Click Copy Kubeconfig File to copy the kubeconfig content to your clipboard.

Step 2: Save the kubeconfig file

Save the copied content to the default kubectl configuration file at $HOME/.kube/config:

# Create the directory if it does not exist
mkdir -p $HOME/.kube

# Write the kubeconfig content to the config file
cat > $HOME/.kube/config << 'EOF'
<paste-kubeconfig-content-here>
EOF

Note

If $HOME/.kube/config already contains credentials for other clusters, save the ASM kubeconfig to a separate file and set the KUBECONFIG environment variable:

cat > $HOME/.kube/asm-config << 'EOF'
<paste-kubeconfig-content-here>
EOF

export KUBECONFIG=$HOME/.kube/asm-config

Step 3: Verify the connection

Run the following command to confirm that kubectl can reach the ASM control plane:

kubectl get ns

Expected output:

NAME              STATUS   AGE
default           Active   30d

A list of namespaces confirms a successful connection. If the command fails, check the following:

The kubeconfig file is saved to the correct path.
Your network can reach the ASM API server -- an EIP is required for internet access, or VPC connectivity for internal access.
The kubeconfig content was copied in full without truncation.

Next steps

After you connect kubectl to the ASM control plane, you can manage Istio resources directly from the command line. Common tasks include:

Create traffic management rules such as VirtualService and DestinationRule resources.
Configure ingress gateways to route external traffic into the mesh.
Apply security policies such as AuthorizationPolicy and PeerAuthentication resources.
List and inspect existing Istio resources with kubectl get and kubectl describe.