From 7bb8430d96bf7a14f39d5b2924fe533b33bd52e1 Mon Sep 17 00:00:00 2001 From: njg7194 Date: Sun, 1 Feb 2026 15:02:40 +0900 Subject: [PATCH] docs: add PowerShell usage guide - Add comprehensive PowerShell usage documentation (powershell_usage.md) - Cover basic commands, script execution, Azure integration, and DevOps workflows - Update main README.md to link PowerShell guide (was TODO) - Update docs/usage/README.md to include PowerShell section Partially addresses #126 --- README.md | 2 +- docs/usage/README.md | 4 + docs/usage/powershell_usage.md | 140 +++++++++++++++++++++++++++++++++ 3 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 docs/usage/powershell_usage.md diff --git a/README.md b/README.md index 932345b..5e62089 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,7 @@ Built on `ubuntu:22.04` base image | Helm | HELM_VERSION=3.17.2 | [Check](https://github.com/helm/helm/releases) | [helm_usage](./docs/usage/helm_usage.md) | | AwsCLI | AWSCLI_VERSION=2.24.24 | [Check](https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst) | [awscli_usage](./docs/usage/awscli_usage.md) | | AzureCLI | AZURECLI_VERSION=2.70.0 | [Check](https://learn.microsoft.com/en-us/cli/azure/release-notes-azure-cli) | [azurecli_usage](./docs/usage/azurecli_usage.md) | -| PowerShell | PS_VERSION=7.5.0 | [Check](https://github.com/PowerShell/PowerShell/releases) | TODO | +| PowerShell | PS_VERSION=7.5.0 | [Check](https://github.com/PowerShell/PowerShell/releases) | [powershell_usage](./docs/usage/powershell_usage.md) | And more tools to be implemented... diff --git a/docs/usage/README.md b/docs/usage/README.md index f84637a..664c25b 100644 --- a/docs/usage/README.md +++ b/docs/usage/README.md @@ -30,6 +30,10 @@ This guide us how to use the `devops-toolkit` with serveral usecases - Check [**azurecli_usage**](./azurecli_usage.md) +## PowerShell + +- Check [**powershell_usage**](./powershell_usage.md) + ## Troubleshooting - For any issues, check [this document](../troubleshooting/TROUBLESHOOTING.md) diff --git a/docs/usage/powershell_usage.md b/docs/usage/powershell_usage.md new file mode 100644 index 0000000..5074c46 --- /dev/null +++ b/docs/usage/powershell_usage.md @@ -0,0 +1,140 @@ +# Use PowerShell in the devops-toolkit + +## Overview + +PowerShell is a cross-platform task automation solution made up of a command-line shell, a scripting language, and a configuration management framework. It runs on Windows, Linux, and macOS. + +## PowerShell documentation + +Some resources to help you start with PowerShell: + +- +- +- + +## Run with Docker command + +### Note + +To use the existing container instead of creating one, use `docker exec` command instead of `docker run` + +```bash +docker exec -it my_devops_toolkit /bin/bash +``` + +### Common Run Modes + +For instructions on common run modes, visit [**DevOps Toolkit Common Run Mode**](../usage/run_mode.md). + +### Use case 1: Start PowerShell and run basic commands + +```bash +docker run --rm --network host -it tungbq/devops-toolkit:latest +############################################### +# Now we are in the docker container terminal # +############################################### +# Start PowerShell +pwsh +``` + +Once in PowerShell, you can run commands: + +```powershell +# Check PowerShell version +$PSVersionTable + +# Get current directory +Get-Location + +# List files +Get-ChildItem + +# Exit PowerShell +exit +``` + +Sample Result + +```bash +root@docker-desktop:~# pwsh +PowerShell 7.5.0 +PS /root> $PSVersionTable + +Name Value +---- ----- +PSVersion 7.5.0 +PSEdition Core +GitCommitId 7.5.0 +OS Linux 5.15.167.4-microsoft-standard-WSL2 #1 SMP ... +Platform Unix +PSCompatibleVersions {1.0, 2.0, 3.0, 4.0…} +PSRemotingProtocolVersion 2.3 +SerializationVersion 1.1.0.1 +WSManStackVersion 3.0 +``` + +### Use case 2: Run a PowerShell script + +```bash +docker run --rm --network host -it -v "$PWD:$PWD" -w "$PWD" tungbq/devops-toolkit:latest +############################################### +# Now we are in the docker container terminal # +############################################### +# Run a PowerShell script +pwsh -File ./your-script.ps1 + +# Or run inline PowerShell command +pwsh -Command "Get-Process | Select-Object -First 5" +``` + +### Use case 3: Use PowerShell with Azure + +PowerShell is commonly used with Azure for cloud automation: + +```bash +docker run --rm --network host -it -v ~/.dtc:/dtc tungbq/devops-toolkit:latest +############################################### +# Now we are in the docker container terminal # +############################################### +pwsh +``` + +In PowerShell: + +```powershell +# Import Azure module (if needed) +Import-Module Az + +# Connect to Azure (opens browser for authentication) +Connect-AzAccount + +# List Azure subscriptions +Get-AzSubscription + +# List Resource Groups +Get-AzResourceGroup +``` + +### Use case 4: Common PowerShell commands for DevOps + +```powershell +# Working with JSON +$json = '{"name": "devops-toolkit", "version": "1.0"}' | ConvertFrom-Json +$json.name + +# Working with REST APIs +Invoke-RestMethod -Uri "https://api.github.com/repos/tungbq/devops-toolkit" | Select-Object name, stargazers_count + +# Environment variables +$env:PATH + +# File operations +Get-Content ./README.md | Select-Object -First 10 + +# Process management +Get-Process | Sort-Object CPU -Descending | Select-Object -First 5 +``` + +## Troubleshooting + +- For any issues, check [this reference](../troubleshooting/TROUBLESHOOTING.md)