From aad8b88866a09de5ddfb58958b765fe69d78d173 Mon Sep 17 00:00:00 2001 From: Qasim Sarfraz Date: Fri, 27 Oct 2023 18:22:34 +0200 Subject: [PATCH] docs: Add exec-doc for run-command Signed-off-by: Qasim Sarfraz --- .github/workflows/kubectl-aks.yml | 43 ++++++++++++++++++++++++++----- .gitignore | 1 + Makefile | 8 +++++- docs/run-command.ini.sample | 4 +++ docs/run-command.md | 40 ++++++++++++++++++++-------- 5 files changed, 78 insertions(+), 18 deletions(-) create mode 100644 docs/run-command.ini.sample diff --git a/.github/workflows/kubectl-aks.yml b/.github/workflows/kubectl-aks.yml index 23ff2e1..5772485 100644 --- a/.github/workflows/kubectl-aks.yml +++ b/.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) @@ -114,7 +114,8 @@ jobs: needs: [ build, lint, unit-tests ] runs-on: ubuntu-latest outputs: - nodes: ${{ steps.nodes.outputs.result }} + test-nodes: ${{ steps.nodes.outputs.test }} + docs-nodes: ${{ steps.nodes.outputs.docs }} strategy: fail-fast: false matrix: @@ -148,7 +149,10 @@ jobs: --resource-group ${{ env.AZURE_PREFIX }}-rg \ --name ${{ env.AZURE_PREFIX }}-${{ matrix.arch }}-cluster \ --admin - echo "result=$(kubectl get nodes -o jsonpath='{.items[*].metadata.name}' | jq -R -s -c 'split(" ")')" >> $GITHUB_OUTPUT + + NODES=$(kubectl get nodes -o jsonpath='{.items[*].metadata.name}' | jq -R -s -c 'split(" ")') + echo "test=$(echo $NODES | jq -c .[0:3])" >> $GITHUB_OUTPUT + echo "docs=$(echo $NODES | jq -c .[3:4])" >> $GITHUB_OUTPUT delete-aks-cluster: name: Delete AKS cluster @@ -255,13 +259,19 @@ jobs: export AZURE_RESOURCE_GROUP=${{ env.AZURE_PREFIX }}-rg export AZURE_CLUSTER_NAME=${{ env.AZURE_PREFIX }}-${{ matrix.arch }}-cluster export AZURE_SUBSCRIPTION_ID=${{ secrets.AZURE_AKS_SUBSCRIPTION_ID }} - export AZURE_NODE_NAME=$(echo '${{ needs.create-aks-cluster.outputs.nodes }}' | jq -r ".[${{ strategy.job-index }}]") + export AZURE_NODE_NAME=$(echo '${{ needs.create-aks-cluster.outputs.test-nodes }}' | jq -r ".[${{ strategy.job-index }}]") make integration-test -o kubectl-aks 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 @@ -269,6 +279,18 @@ jobs: 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 +305,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.docs-nodes }}' | jq -r ".[0]")" >> $f + done - name: Test docs - run: make test-docs + run: make test-docs -o install release: name: Release diff --git a/.gitignore b/.gitignore index 7e510d7..708d063 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ *.so *.log *.dylib +*.ini /kubectl-aks /kubectl-aks-*-* diff --git a/Makefile b/Makefile index ee06a0c..03e1c24 100644 --- a/Makefile +++ b/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 diff --git a/docs/run-command.ini.sample b/docs/run-command.ini.sample new file mode 100644 index 0000000..39c0ca1 --- /dev/null +++ b/docs/run-command.ini.sample @@ -0,0 +1,4 @@ +mySubID = mySubID +myRG = myRG +myCluster = myCluster +myNode = myNode diff --git a/docs/run-command.md b/docs/run-command.md index 8610112..c438024 100644 --- a/docs/run-command.md +++ b/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 +``` + +``` 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" +``` + +``` 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,19 +55,25 @@ 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" +``` + +``` 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 + +``` 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 ``` @@ -63,13 +81,13 @@ kubectl aks run-command "ip route" --subscription $SUBSCRIPTION --node-resource- 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