diff --git a/.github/workflows/releaser-internal.yaml b/.github/workflows/releaser-internal.yaml index a49fdbc..059b96d 100644 --- a/.github/workflows/releaser-internal.yaml +++ b/.github/workflows/releaser-internal.yaml @@ -62,6 +62,6 @@ jobs: with: distribution: goreleaser version: v2.9.0 - args: release --clean --prerelease + args: release --clean env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index 6c0c9e4..5637132 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ - [Usage](#usage) - [Commands](#commands) - [Contributing](#contributing) -- [Code Review Automation](#code-review-automation) +- [Code Review Automation](#code-review-automation) - [Releasing](#releasing) - [Credits](#credits) - [License](#license) @@ -97,7 +97,7 @@ chmod +x install-awsctl.sh 3. Run the startup script: - #### First Time Installation -If this is your first time installing, use the `source` command: + If this is your first time installing, use the `source` command: ```bash source ./install-awsctl.sh @@ -106,11 +106,13 @@ source ./install-awsctl.sh This ensures environment changes (like `PATH` updates) take effect immediately. ### Why use `source`? + - Executes in current shell session - Updates environment variables immediately - No terminal restart required ### For Updates + Run normally: ```bash @@ -136,26 +138,25 @@ ssoSessions: startUrl: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" region: "XX-XXXX-X" scopes: "sso:account:access" - - ``` + **Note**: `scopes` can be empty. Default value will be `sso:account:access` + ### Commands The following table summarizes the available `awsctl` commands: -| Command | Description | -|--------------------|---------------------------------------------------------------------------------------------------| -| `awsctl sso setup` | Creates or updates an AWS SSO profile. Uses config file in `~/.config/awsctl/` if available, or prompts for required details. Optionally sets it as the default and authenticates. | -| `awsctl sso init` | Starts SSO authentication by allowing you to select from existing AWS SSO profiles (created via `awsctl sso setup`). Useful for switching between multiple configured SSO profiles. | -| `awsctl bastion` | Manages SSH/SSM connections, SOCKS proxy, or port forwarding to bastion hosts or EC2 instances. | -| `awsctl rds` | Connects to RDS databases directly or via SSH/SSM tunnels. | -| `awsctl eks` | Updates kubeconfig for accessing Amazon EKS clusters. | -| `awsctl ecr` | Authenticates to Amazon ECR for container image operations. | +| Command | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `awsctl sso setup` | Creates or updates an AWS SSO profile. If a config file is available at `~/.config/awsctl/`, it will be used; otherwise, you will be prompted to enter the SSO Start URL and Region. The selected profile is then set as the default and authenticated. | +| `awsctl sso init` | Starts SSO authentication by allowing you to select from existing AWS SSO profiles (created via `awsctl sso setup`). Useful for switching between multiple configured SSO profiles. | +| `awsctl bastion` | Manages SSH/SSM connections, SOCKS proxy, or port forwarding to bastion hosts or EC2 instances. | +| `awsctl rds` | Connects to RDS databases directly or via SSH/SSM tunnels. | +| `awsctl eks` | Updates kubeconfig for accessing Amazon EKS clusters. | +| `awsctl ecr` | Authenticates to Amazon ECR for container image operations. | #### For detailed CLI command usage, see [Command Usage Documentation](docs/usage/commands.md). - ### Contributing We welcome contributions! Please see our [contributing guidelines](CONTRIBUTING.md) for more details. @@ -167,13 +168,13 @@ This project uses [Coderabbit AI](https://www.coderabbit.ai/) to assist with pul **Role**: Automatically reviews pull requests for code quality, potential bugs, best practices, and documentation gaps. **How it works**: + - Summarizes PR changes. - Provides line-by-line suggestions. - Offers codebase-wide analysis. **Note**: Suggestions by Coderabbit are recommendations. Final review decisions are made by maintainers. - ### Releasing To trigger a release, push a commit to `main` with `[release]` in the commit message (e.g., `git commit -m "Add feature [release]"`). The workflow will auto-increment the version, tag it, and create a draft release. diff --git a/docs/usage/commands.md b/docs/usage/commands.md index 811ec51..08d651b 100644 --- a/docs/usage/commands.md +++ b/docs/usage/commands.md @@ -3,19 +3,19 @@ ## Commands ### `awsctl sso setup` + Creates or updates AWS SSO profiles. - Prompts for: - SSO Start URL - AWS Region - - Scopes (default: `sso:account:access`) - - Option to set as default profile - Uses defaults from `~/.config/awsctl/config.yml` if available. -- Authenticates the profile immediately after setup. +- Automatically sets the profile as default and authenticates it after setup. --- ### `awsctl sso init` + Starts SSO authentication using one of the configured SSO profiles. - Selects from available profiles created via `awsctl sso setup` @@ -25,10 +25,13 @@ Starts SSO authentication using one of the configured SSO profiles. --- ### `awsctl bastion` + Manages connections to bastion hosts via SSH, SSM, or tunnels. #### Instance Detection + - If SSO is configured, prompts: + - "Look for bastion hosts in AWS?" - If yes, searches for EC2 instances with the name or tags containing `bastion` for the **selected profile**. - Allows easier selection from discovered instances. @@ -38,6 +41,7 @@ Manages connections to bastion hosts via SSH, SSM, or tunnels. - Allows manual entry of bastion host, SSH username, and SSH key. #### Connection Options + 1. SSH: - Public or Private IP (uses EC2 Instance Connect if needed). 2. SSM: @@ -47,6 +51,7 @@ Manages connections to bastion hosts via SSH, SSM, or tunnels. #### Requirements for SSM and EC2 Instance Connect **1. SSM (AWS Systems Manager) Requirements** + - **IAM Role Attached to Instance**: - Must have the following AWS managed policies (or equivalent custom policies): - `AmazonSSMManagedInstanceCore` @@ -60,19 +65,21 @@ Manages connections to bastion hosts via SSH, SSM, or tunnels. - Ensure the **SSM Agent** is installed and running on the EC2 instance. **2. EC2 Instance Connect Requirements** + - **IAM Permissions for Caller/User**: - `ec2-instance-connect:SendSSHPublicKey` - `ec2:DescribeInstances` - `ec2:GetConsoleOutput` (optional) - **Public DNS/IP Access**: + - The instance **must have a public IPv4 address or public DNS**, unless used via a bastion or SSM tunnel. - **VPC Endpoint (Required if the instance is in a private subnet without internet access)**: - Create an **Interface VPC Endpoint** for `com.amazonaws..ec2-instance-connect` - Required if the instance is in a private subnet without internet access, allowing EC2 Instance Connect API calls to AWS securely. - #### Extras + - **SOCKS5 Proxy**: - Prompts for: - SOCKS proxy port (default: `1080`) @@ -88,24 +95,30 @@ Manages connections to bastion hosts via SSH, SSM, or tunnels. --- ### `awsctl rds` + Connects to RDS databases with flexibility. #### Supported Modes: + - **Direct Connect**: If the RDS instance is publicly accessible. - **Via Bastion**: SSH or SSM tunnel through a bastion host. #### Supported Databases: + - PostgreSQL, MySQL, others (depending on configuration). - Dynamic port assignment to avoid collisions. #### Authentication Methods + - **Token** (IAM Database Authentication) - **Native Password** (Database user password) ##### Native Password + - Use the **initial password** defined when creating the RDS instance or the password configured for that database user. ##### Token (IAM Authentication) + - Requires **IAM database authentication** to be enabled on the RDS instance. - **For MySQL**: - Users must be configured with the `AWSAuthenticationPlugin`. @@ -114,29 +127,37 @@ Connects to RDS databases with flexibility. - You can either **create a new IAM-auth-enabled database user** or **alter existing users** to support IAM-based login. ###### Example: Enable IAM Authentication for Database Users + **MySQL:** + ```sql CREATE USER 'dbuser'@'%' IDENTIFIED WITH AWSAuthenticationPlugin as 'RDS'; GRANT ALL PRIVILEGES ON database_name.* TO 'dbuser'@'%'; ``` **PostgreSQL:** + ```sql CREATE USER dbuser WITH LOGIN; GRANT rds_iam TO dbuser; ``` + --- ### `awsctl eks` + Simplifies access to Amazon EKS clusters. -- Features: - - Lists available EKS clusters for the AWS profile/region. - - Updates or generates `~/.kube/config` with the selected cluster’s credentials. +- Prompts for: + - **AWS Region** + - **SSO Profile** (fetched from `~/.aws/config`; must be set up via `awsctl sso setup`) +- Lists available EKS clusters for the selected region and profile. +- Prompts you to select a cluster and updates (or creates) your `~/.kube/config` with the cluster’s credentials. --- ### `awsctl ecr` + Handles authentication to Amazon ECR for Docker or container image workflows. - Features: @@ -155,3 +176,4 @@ awsctl bastion awsctl rds awsctl eks awsctl ecr +```