Skip to content

Commit 883a11e

Browse files
patrickleetpatrickleet
committed
chore: readme updates
1 parent e7eb623 commit 883a11e

2 files changed

Lines changed: 124 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 123 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -80,62 +80,150 @@ hops validate --help
8080
hops xr --help
8181
```
8282

83-
From source without installing:
83+
## Create a Local Control Plane
8484

8585
```bash
86-
cargo run -- --help
87-
cargo run -- local --help
88-
cargo run -- config --help
89-
cargo run -- validate --help
90-
cargo run -- xr --help
86+
# 1) Install Colima (via Homebrew)
87+
hops local install
88+
89+
# 2) Start local k8s + Crossplane + providers + local registry
90+
hops local start
91+
92+
# 3) Configure AWS provider-family + ProviderConfig from your AWS profile
93+
hops local aws --profile <aws-profile>
94+
95+
# 4) Configure GitHub provider + ProviderConfig from your gh auth login
96+
hops local github --owner <org-or-user>
97+
98+
# 5) Install a Crossplane configuration package from an Upbound-format XRD project
99+
hops config install --repo hops-ops/aws-auto-eks-cluster --version v0.11.0
91100
```
92101

102+
### Local provider setup and auth
103+
104+
`hops local aws` and `hops local github` install the provider package and bootstrap auth into a local control plane. The exception is `--refresh`, which updates credentials only.
105+
106+
#### AWS auth
107+
108+
`hops local aws` installs the AWS provider package and uses your AWS CLI configuration to generate credentials for it.
109+
110+
```bash
111+
# Use an explicit AWS profile
112+
hops local aws --profile hops
113+
114+
# Refresh only the Secret credentials without re-applying the Provider or ProviderConfig
115+
hops local aws --profile hops --refresh
116+
```
117+
118+
How it works:
119+
120+
- Resolves the profile in this order: `--profile`, `AWS_PROFILE`, `AWS_DEFAULT_PROFILE`, then interactive prompt.
121+
- Runs `aws configure export-credentials --format process`.
122+
- If the selected profile needs AWS SSO login, it runs `aws sso login --profile <profile>` and retries once.
123+
- Applies the AWS provider package unless `--refresh` is used.
124+
- Writes the generated credentials into a Kubernetes Secret, defaulting to `default/aws-creds`.
125+
- Applies an AWS `ProviderConfig` named `default` unless `--refresh` is used.
126+
- Supports overrides for namespace, Secret name, ProviderConfig name, provider name, and provider package.
127+
128+
#### GitHub auth
129+
130+
`hops local github` installs the GitHub provider package and uses your GitHub CLI login to generate credentials for it.
131+
132+
```bash
133+
# Use an explicit owner
134+
hops local github --owner hops-ops
135+
136+
# Refresh only the Secret credentials without re-applying the Provider or ProviderConfig
137+
hops local github --owner hops-ops --refresh
138+
```
139+
140+
How it works:
141+
142+
- Resolves the owner in this order: `--owner`, `GH_OWNER`, `GITHUB_OWNER`, then interactive prompt.
143+
- Uses your current `gh auth token`.
144+
- If `gh` is not authenticated, it runs `gh auth login` and retries once.
145+
- Applies the GitHub provider package unless `--refresh` is used.
146+
- Writes the generated credentials into a Kubernetes Secret, defaulting to `default/github-creds`.
147+
- Applies a GitHub `ProviderConfig` named `default` unless `--refresh` is used.
148+
- Supports overrides for namespace, Secret name, ProviderConfig name, provider name, and provider package.
149+
93150
## Quick Start
94151

95152
```bash
96-
# 1) Install Colima (via Homebrew)
97-
cargo run -- local install
153+
# Build and load a Crossplane configuration package from an Upbound-format XRD project
154+
hops config install --path /path/to/project
98155

99-
# 2) Start local k8s + Crossplane + providers + local registry
100-
cargo run -- local start
156+
# Build from a GitHub repo containing an Upbound-format XRD project
157+
hops config install --repo hops-ops/helm-certmanager
101158

102-
# 3) Configure AWS provider-family + ProviderConfig from your AWS profile
103-
cargo run -- local aws --profile <aws-profile>
159+
# Force reload from source (deletes existing ConfigurationRevision(s) first)
160+
hops config install --repo hops-ops/helm-certmanager --reload
104161

105-
# 4) Configure GitHub provider + ProviderConfig from your gh auth login
106-
cargo run -- local github --owner <org-or-user>
162+
# Apply a pinned remote package version directly (no clone/build)
163+
hops config install --repo hops-ops/helm-certmanager --version v0.1.0
164+
165+
# Remove a configuration and prune orphaned package dependencies
166+
hops config uninstall --repo hops-ops/helm-certmanager
167+
168+
# Generate apis/*/configuration.yaml from upbound.yaml for validation
169+
hops validate generate-configuration --path /path/to/project
170+
171+
# Observe an existing XR into a manifest
172+
hops xr observe --kind AutoEKSCluster --name pat-local --namespace default --aws-region us-east-2
173+
174+
# Render adoption patches for managed resources under an existing XR
175+
hops xr adopt --kind AutoEKSCluster --name pat-local --namespace default
107176

108-
# 5) Build and load a Crossplane configuration package from an XRD project
109-
cargo run -- config install --path /path/to/project
177+
# Convert an observed/adopted XR into a managed manifest
178+
hops xr manage --kind AutoEKSCluster --name pat-local --namespace default
110179

111-
# 6) Build from a GitHub repo (cached clone + build + push to local registry)
112-
cargo run -- config install --repo hops-ops/helm-certmanager
180+
# Render patches that remove Delete from management policies
181+
hops xr orphan --kind AutoEKSCluster --name pat-local --namespace default
182+
```
113183

114-
# 7) Force reload from source (deletes existing ConfigurationRevision(s) first)
115-
cargo run -- config install --repo hops-ops/helm-certmanager --reload
184+
## Config packages
116185

117-
# 8) Apply a pinned remote package version directly (no clone/build)
118-
cargo run -- config install --repo hops-ops/helm-certmanager --version v0.1.0
186+
`config install` and `config uninstall` operate on the currently connected Kubernetes cluster.
187+
`config install` expects an Upbound-format XRD project when building from source via `--path` or `--repo`.
119188

120-
# 9) Remove a configuration and prune orphaned package dependencies
121-
cargo run -- config uninstall --repo hops-ops/helm-certmanager
189+
Common install flows:
122190

123-
# 10) Generate apis/*/configuration.yaml from upbound.yaml for validation
124-
cargo run -- validate generate-configuration --path /path/to/project
191+
```bash
192+
# Build from the current directory when it is an Upbound-format XRD project
193+
hops config install
125194

126-
# 11) Observe an existing XR into a manifest
127-
cargo run -- xr observe --kind AutoEKSCluster --name pat-local --namespace default --aws-region us-east-2
195+
# Build from an explicit local Upbound-format XRD project path
196+
hops config install --path /path/to/project
128197

129-
# 12) Render adoption patches for managed resources under an existing XR
130-
cargo run -- xr adopt --kind AutoEKSCluster --name pat-local --namespace default
198+
# Build from a cached GitHub repo checkout containing an Upbound-format XRD project
199+
hops config install --repo hops-ops/helm-certmanager
131200

132-
# 13) Convert an observed/adopted XR into a managed manifest
133-
cargo run -- xr manage --kind AutoEKSCluster --name pat-local --namespace default
201+
# Force a source reload before re-applying
202+
hops config install --repo hops-ops/helm-certmanager --reload
134203

135-
# 14) Render patches that remove Delete from management policies
136-
cargo run -- xr orphan --kind AutoEKSCluster --name pat-local --namespace default
204+
# Apply a pinned remote package directly from ghcr.io
205+
hops config install --repo hops-ops/helm-certmanager --version v0.1.0
137206
```
138207

208+
Common uninstall flows:
209+
210+
```bash
211+
# Remove by explicit configuration name
212+
hops config uninstall --name hops-ops-helm-certmanager
213+
214+
# Remove by repo slug
215+
hops config uninstall --repo hops-ops/helm-certmanager
216+
217+
# Remove configurations derived from local build artifacts
218+
hops config uninstall --path /path/to/project
219+
```
220+
221+
Notes:
222+
223+
- `--reload` only applies to source installs: `--path` or `--repo` without `--version`.
224+
- `config install --repo ... --version ...` skips clone/build and applies the remote package directly.
225+
- `config uninstall --repo ...` derives the configuration name as `<org>-<repo>`.
226+
139227
## Commands
140228

141229
- `local install`
@@ -253,7 +341,7 @@ Notes:
253341
Set `LOG_LEVEL` to control output (default: `info`):
254342

255343
```bash
256-
LOG_LEVEL=debug cargo run -- local start
344+
LOG_LEVEL=debug hops local start
257345
```
258346

259347
## Development

‎src/main.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ struct Args {
1212

1313
#[derive(Subcommand, Debug)]
1414
enum Commands {
15-
/// Manage the local development environment
15+
/// Manage the local control plane environment
1616
Local(commands::local::LocalArgs),
1717
/// Manage Crossplane configuration packages in the connected cluster
1818
Config(commands::config::ConfigArgs),

0 commit comments

Comments
 (0)