Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/releaser-internal.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
29 changes: 15 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand Down
36 changes: 29 additions & 7 deletions docs/usage/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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.
Expand All @@ -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:
Expand All @@ -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`
Expand All @@ -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.<region>.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`)
Expand All @@ -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`.
Expand All @@ -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:
Expand All @@ -155,3 +176,4 @@ awsctl bastion
awsctl rds
awsctl eks
awsctl ecr
```
Loading