docs: Add exec-doc for run-command

Signed-off-by: Qasim Sarfraz <qasimsarfraz@microsoft.com>

.github/workflows/kubectl-aks.yml

@@ -2,7 +2,7 @@ name: Azure Kubernetes Service kubectl plugin CI
 env:
   GO_VERSION: 1.18
   AZURE_PREFIX: kubectl-aks-ci
-  AZURE_NODE_COUNT: 3
+  AZURE_NODE_COUNT: 4
 concurrency:
   # Only one workflow can run at a time unless
   # we create a new AKS cluster per github_ref (branch)
@@ -261,14 +261,32 @@ jobs:
   test-docs:
     name: Test docs
     runs-on: ubuntu-latest
-    needs: [ build, unit-tests ]
+    needs: [ build, unit-tests, create-aks-cluster ]
+    environment: aks
+    permissions:
+      # This is needed to use federated credentials:
+      # https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-cli%2Clinux#set-up-azure-login-with-openid-connect-authentication
+      id-token: write
+      contents: read
     steps:
       - uses: actions/checkout@v3
       - name: Setup go
         uses: actions/setup-go@v4
         with:
           go-version: '>=1.20.0' # ie requires go 1.20+
           check-latest: true
+      - name: Login to Azure
+        uses: azure/login@v1
+        with:
+          client-id: ${{ secrets.AZURE_AKS_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_AKS_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_AKS_SUBSCRIPTION_ID }}
+      - name: Set AKS cluster context
+        uses: azure/aks-set-context@v3
+        with:
+          cluster-name: ${{ env.AZURE_PREFIX }}-amd64-cluster
+          resource-group: ${{ env.AZURE_PREFIX }}-rg
+          admin: false
       - name: Get kubectl-aks from artifact
         uses: actions/download-artifact@v3
         with:
@@ -283,8 +301,17 @@ jobs:
       - name: Download ie
         run: |
           go install github.com/Azure/InnovationEngine/cmd/ie@03880d11fadcf98e39c465248aa1d5b64f99cdb7
+      - name: Prepare variables files
+        run: |
+          VAR_FILES="./docs/run-command.ini"
+          for f in $VAR_FILES; do
+              echo "mySubID = ${{ secrets.AZURE_AKS_SUBSCRIPTION_ID }}" >> $f
+              echo "myRG = ${{ env.AZURE_PREFIX }}-rg" >> $f
+              echo "myCluster = ${{ env.AZURE_PREFIX }}-amd64-cluster" >> $f
+              echo "myNode = $(echo '${{ needs.create-aks-cluster.outputs.nodes }}' | jq -r ".[3]")" >> $f
+          done
       - name: Test docs
-        run: make test-docs
+        run: make test-docs -o kubectl-aks
 
   release:
     name: Release

.gitignore

@@ -5,6 +5,7 @@
 *.so
 *.log
 *.dylib
+*.ini
 /kubectl-aks
 /kubectl-aks-*-*
 

Makefile

@@ -84,10 +84,16 @@ integration-test: kubectl-aks
 		go test -v ./test/integration/... -integration
 
 # Test docs using Executable Documentation by Innovation Engine
+TEST_DOCS_FILES ?= \
+	README.md \
+	./docs/run-command.md
+
 .PHONY: test-docs
 test-docs: install
 	ie --help > /dev/null || (echo "ie is not installed, please install it from https://github.com/Azure/InnovationEngine" && exit 1)
-	ie execute README.md
+	for file in $(TEST_DOCS_FILES); do \
+		ie execute $$file; \
+	done
 
 # Clean
 .PHONY: clean

docs/run-command.ini.sample

@@ -0,0 +1,4 @@
+mySubID = mySubID
+myRG = myRG
+myCluster = myCluster
+myNode = myNode

docs/run-command.md

@@ -9,11 +9,18 @@ of running scripts in an Azure Linux VM also apply here.
 ## Regardless of the Kubernetes control plane status
 
 When executing `run-command` without passing through Kubernetes, we need to provide the information of the node (VMSS instance) where we want to run the given command. To retrieve such information, we can use the [`config import`](./config.md#importing-configuration) command. Once we got it, we can select the node we want to use and all the subsequent `run-command` commands will be executed on that node:
-
 ```bash
+# Clean the current configuration (if any)
+kubectl aks config unset-all
 # Import the nodes information with the cluster information
-$ kubectl aks config import --subscription mySubID --resource-group myRG --cluster-name myCluster
-$ kubectl aks config show
+kubectl aks config import --subscription $mySubID --resource-group $myRG --cluster-name $myCluster
+```
+
+```bash
+kubectl aks config show
+```
+<!--expected_similarity=0.8-->
+```
 nodes:
     aks-agentpool-12345678-vmss000000:
         instance-id: "0"
@@ -26,12 +33,17 @@ nodes:
     aks-agentpool-12345678-vmss000002:
         instance-id: "2"
         [...]
+```
 
-# Start using one of those nodes
-$ kubectl aks use-node aks-agentpool-12345678-vmss000000
+```bash
+# Start using one of above node e.g aks-agentpool-12345678-vmss000000
+kubectl aks config use-node $myNode
 
 # Execute the run-command, and it will be automatically executed in aks-agentpool-12345678-vmss000000
-$ kubectl aks run-command "ip route"
+kubectl aks run-command "ip route"
+```
+<!--expected_similarity=0.8-->
+```
 default via 10.240.0.1 dev eth0 proto dhcp src 10.240.0.4 metric 100
 10.240.0.0/16 dev eth0 proto kernel scope link src 10.240.0.4
 10.244.2.2 dev calic38a36632c7 scope link
@@ -43,33 +55,39 @@ default via 10.240.0.1 dev eth0 proto dhcp src 10.240.0.4 metric 100
 10.244.2.14 dev cali8eecb1f59c6 scope link
 168.63.129.16 via 10.240.0.1 dev eth0 proto dhcp src 10.240.0.4 metric 100
 169.254.169.254 via 10.240.0.1 dev eth0 proto dhcp src 10.240.0.4 metric 100
+```
 
+```bash
 # Another command that will be still executed in aks-agentpool-12345678-vmss000000
-$ kubectl aks run-command "hostname"
+kubectl aks run-command "hostname"
+```
+<!--expected_similarity=0.8-->
+```
 aks-agentpool-12345678-vmss000000
 ```
 
 On the other side, if we already have the node (VMSS instance) information and we don't want/need to save it locally, we could pass it directly as following:
 
-```bash
+<!-- TODO: testing following commands -->
+```
 kubectl aks run-command "ip route" --id "/subscriptions/$SUBSCRIPTION/resourceGroups/$NODERESOURCEGROUP/providers/Microsoft.Compute/virtualMachineScaleSets/$VMSS/virtualmachines/$INSTANCEID"
 ```
 
-```bash
+```
 kubectl aks run-command "ip route" --subscription $SUBSCRIPTION --node-resource-group $NODERESOURCEGROUP --vmss $VMSS --instance-id $INSTANCEID
 ```
 
 ## Passing through Kubernetes
 
 If we are debugging a node while the Kubernetes control plane is up and running, we can simply pass the node name to the `run-command` and it will internally retrieve all the data it needs from the API server to execute the command in that node:
 
-```bash
+```
 kubectl aks run-command "ip route" --node aks-agentpool-12345678-vmss000000
 ```
 
 In addition, if we need to run multiple commands on a node, we can still use the [`config import`](./config.md#importing-configuration) command to import the information of all the nodes of our cluster, and this time we don't need to pass the cluster information as `run-command` will retrieve it from the API server:
 
-```bash
+```
 # Import the nodes information from the API server
 kubectl aks config import