Skip to content

Commit 3078374

Browse files
joaopaletvicentepinto98
joaopalet
authored and
vicentepinto98
committed
Initial commit
0 parents  commit 3078374

File tree

298 files changed

+36228
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

298 files changed

+36228
-0
lines changed

‎.github/actions/build/action.yaml

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: Build
2+
description: "Build pipeline"
3+
inputs:
4+
go-version:
5+
description: "Go version to install"
6+
required: true
7+
runs:
8+
using: "composite"
9+
steps:
10+
- name: Install Go ${{ inputs.go-version }}
11+
uses: actions/setup-go@v4
12+
with:
13+
go-version: ${{ inputs.go-version }}
14+
- name: Install project tools and dependencies
15+
shell: bash
16+
run: make project-tools

‎.github/workflows/ci.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: CI Workflow
2+
3+
on: [pull_request, workflow_dispatch]
4+
5+
env:
6+
GO_VERSION: "1.21"
7+
8+
jobs:
9+
main:
10+
name: CI
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
- name: Build
16+
uses: ./.github/actions/build
17+
with:
18+
go-version: ${{ env.GO_VERSION }}
19+
- name: Lint
20+
run: make lint
21+
- name: Test
22+
run: make test

‎.github/workflows/release.yaml

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# STACKIT CLI release workflow.
2+
name: Release
3+
4+
# This GitHub action creates a release when a tag that matches the pattern
5+
# "v*" (e.g. v0.1.0) is created.
6+
on:
7+
push:
8+
tags:
9+
- "v*"
10+
workflow_dispatch:
11+
12+
# Releases need permissions to read and write the repository contents.
13+
# GitHub considers creating releases and uploading assets as writing contents.
14+
permissions:
15+
contents: write
16+
17+
jobs:
18+
goreleaser:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
with:
23+
# Allow goreleaser to access older tag information.
24+
fetch-depth: 0
25+
- uses: actions/setup-go@v4
26+
with:
27+
go-version-file: "go.mod"
28+
cache: true
29+
- name: Run GoReleaser
30+
uses: goreleaser/goreleaser-action@v5
31+
with:
32+
args: release --clean
33+
env:
34+
GITHUB_TOKEN: ${{ secrets.CLI_RELEASE }}

‎.gitignore

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Binaries
2+
bin/
3+
dist/
4+
5+
# IDE
6+
.vscode
7+
8+
# OS generated files
9+
.DS_Store

‎.goreleaser.yaml

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
before:
2+
hooks:
3+
- go mod tidy
4+
5+
builds:
6+
- id: linux-builds
7+
env:
8+
- CGO_ENABLED=0
9+
goos:
10+
- linux
11+
binary: "stackit"
12+
13+
- id: windows-builds
14+
env:
15+
- CGO_ENABLED=0
16+
goos:
17+
- windows
18+
binary: "stackit"
19+
20+
- id: macos-builds
21+
env:
22+
- CGO_ENABLED=0
23+
goos:
24+
- darwin
25+
binary: "stackit"
26+
27+
archives:
28+
- format: tar.gz
29+
# This name template makes the OS and Arch compatible with the results of `uname`
30+
name_template: >-
31+
{{ .ProjectName }}_
32+
{{- title .Os }}_
33+
{{- if eq .Arch "amd64" }}x86_64
34+
{{- else if eq .Arch "386" }}i386
35+
{{- else }}{{ .Arch }}{{ end }}
36+
{{- if .Arm }}v{{ .Arm }}{{ end }}
37+
format_overrides:
38+
- goos: windows
39+
format: zip
40+
41+
changelog:
42+
sort: asc
43+
filters:
44+
exclude:
45+
- "^docs:"
46+
- "^test:"
47+
48+
nfpms:
49+
- id: linux-packages
50+
# IDs of the builds for which to create packages for
51+
builds:
52+
- linux-builds
53+
vendor: STACKIT
54+
homepage: https://github.com/stackitcloud/stackit-cli
55+
maintainer: STACKIT <[email protected]>
56+
description: A command-line interface to manage STACKIT resources.
57+
license: Apache 2.0
58+
formats:
59+
- deb
60+
- rpm
61+
62+
brews:
63+
- name: stackit-cli
64+
repository:
65+
owner: stackitcloud
66+
name: homebrew-tap
67+
commit_author:
68+
name: CLI Release Bot
69+
email: [email protected]
70+
homepage: "https://github.com/stackitcloud/stackit-cli"
71+
description: "A command-line interface to manage STACKIT resources."
72+
license: "Apache-2.0"
73+
# If set to auto, the release will not be uploaded to the homebrew tap repo
74+
# if the tag has a prerelease indicator (e.g. v0.0.1-alpha1)
75+
# Not setting it for now to test with a prerelease tag
76+
# skip_upload: auto

‎AUTHENTICATION.md

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Authentication Guide
2+
3+
This document describes how you can configure authentication for the STACKIT CLI.
4+
5+
## Service account
6+
7+
You can use a [service account](https://docs.stackit.cloud/stackit/en/service-accounts-134415819.html) to authenticate to the STACKIT CLI.
8+
The CLI will search for service account credentials similarly to the [STACKIT SDK](https://github.com/stackitcloud/stackit-sdk-go) and [Terraform Provider](https://github.com/stackitcloud/terraform-provider-stackit), so if you have setup you environment previously for those tools, you can just run:
9+
10+
```bash
11+
$ ./bin/stackit auth activate-service-account
12+
```
13+
14+
You can also configure the service account credentials directly in the CLI. To get help and to get a list of the available options run the command with the `-h` flag.
15+
16+
### Overview
17+
18+
If you dont have a service account, create one in the STACKIT Portal an assign it the necessary permissions, e.g. `project.owner`. There are two ways to authenticate:
19+
20+
- Key flow (recommended)
21+
- Token flow
22+
23+
When setting up authentication, the CLI will always try to use the key flow first and search for credentials in several locations, following a specific order:
24+
25+
1. Explicitly provided credentials, e.g. by using the flag `--service-account-key-path`
26+
2. Environment variable, e.g. by setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
27+
3. Credentials file
28+
29+
The CLI will check the credentials file located in the path defined by the `STACKIT_CREDENTIALS_PATH` env var, if specified,
30+
or in `$HOME/.stackit/credentials.json` as a fallback.
31+
The credentials file should be a JSON and each credential should be set using the name of the respective environment variable, as stated below in each flow. Example:
32+
33+
```json
34+
{
35+
"STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token",
36+
"STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json"
37+
}
38+
```
39+
40+
### Key flow
41+
42+
The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. `project.owner`.
43+
44+
To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it.
45+
46+
When creating the service account key, a new RSA key-pair can be created automatically, which will be included in the service account key. This will make it much easier to configure the key flow authentication in the CLI, by just providing the service account key.
47+
48+
**Optionally**, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the CLI, additionaly to the service account key. Check the STACKIT Knowledge Base for an [example of how to create your own key-pair](https://docs.stackit.cloud/stackit/en/usage-of-the-service-account-keys-in-stackit-175112464.html#UsageoftheserviceaccountkeysinSTACKIT-CreatinganRSAkey-pair).
49+
50+
To configure the key flow, follow this steps:
51+
52+
1. Create a service account key:
53+
54+
- In the CLI, run `stackit service-account key create --email <SERVICE_ACCOUNT_EMAIL>`
55+
- As an alternative, use the STACKIT Portal: go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html)
56+
57+
2. Save the content of the service account key by copying it and saving it in a JSON file.
58+
59+
The expected format of the service account key is a **json** with the following structure:
60+
61+
```json
62+
{
63+
"id": "uuid",
64+
"publicKey": "public key",
65+
"createdAt": "2023-08-24T14:15:22Z",
66+
"validUntil": "2023-08-24T14:15:22Z",
67+
"keyType": "USER_MANAGED",
68+
"keyOrigin": "USER_PROVIDED",
69+
"keyAlgorithm": "RSA_2048",
70+
"active": true,
71+
"credentials": {
72+
"kid": "string",
73+
"iss": "[email protected]",
74+
"sub": "uuid",
75+
"aud": "string",
76+
(optional) "privateKey": "private key when generated by the SA service"
77+
}
78+
}
79+
```
80+
81+
3. Configure the service account key for authentication in the CLI by following one of the alternatives below:
82+
83+
- using the flag `--service-account-key-path`
84+
- setting the environment variable `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
85+
- setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` in the credentials file (see above)
86+
87+
> **Optionally, only if you have provided your own RSA key-pair when creating the service account key**, you also need to configure your private key (takes precedence over the one included in the service account key, if present). **The private key must be PEM encoded** and can be provided using one of the options below:
88+
>
89+
> - using the flag `--private-key-path`
90+
> - setting the environment variable `STACKIT_PRIVATE_KEY_PATH`
91+
> - setting `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above)
92+
93+
4. The CLI will search for the keys and, if valid, will use them to get access and refresh tokens which will be used to authenticate all the requests.
94+
95+
### Token flow
96+
97+
Using this flow is less secure since the token is long-lived. You can provide the token in several ways:
98+
99+
1. Providing the flag `--service-account-token`
100+
2. Setting the environment variable `STACKIT_SERVICE_ACCOUNT_TOKEN`
101+
3. Setting `STACKIT_SERVICE_ACCOUNT_TOKEN` in the credentials file (see above)

‎CONTRIBUTION.md

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Contribute to the STACKIT CLI
2+
3+
Your contribution is welcome! Thank you for your interest in contributing to the STACKIT CLI. We greatly value your feedback, feature requests, additions to the code, bug reports or documentation extensions.
4+
5+
## Table of contents
6+
7+
- [Developer Guide](#developer-guide)
8+
- [Code Contributions](#code-contributions)
9+
- [Bug Reports](#bug-reports)
10+
11+
## Developer Guide
12+
13+
### Repository structure
14+
15+
The CLI commands are located under `internal/cmd`, where each folder includes the source code for a `group` of commands. Inside `pkg` you can find several useful packages that are shared by the commands and provide additional functionality such as `flags`, `globalflags`, `tables`, etc.
16+
17+
### Getting started
18+
19+
Check the [Authentication](README.md#authentication) section on the README.
20+
21+
#### Useful Make commands
22+
23+
These commands can be executed from the project root:
24+
25+
- `make project-tools`: install the required dependencies
26+
- `make build`: compiles the CLI and saves the binary under _./bin/stackit_
27+
- `make lint`: lint the code and examples
28+
- `make generate-docs`: generates Markdown documentation for every command
29+
- `make test`: run unit tests
30+
31+
#### Local development
32+
33+
To test your changes, you can either:
34+
35+
1. Build the application locally by running:
36+
37+
```bash
38+
$ go build -o ./bin/stackit
39+
```
40+
41+
To use the application from the root of the repository, you can run:
42+
43+
```bash
44+
$ ./bin/stackit [group] [subgroup] [command] [flags]
45+
```
46+
47+
2. Skip building and run the Go application directly using:
48+
49+
```bash
50+
$ go run . [group] [subgroup] [command] [flags]
51+
```
52+
53+
## Code Contributions
54+
55+
To make your contribution, follow these steps:
56+
57+
1. Check open or recently closed [Pull Requests](https://github.com/stackitcloud/stackit-cli/pulls) and [Issues](https://github.com/stackitcloud/stackit-cli/issues)to make sure the contribution you are making has not been already tackled by someone else.
58+
2. Fork the repo.
59+
3. Make your changes in a branch that is up-to-date with the original repo's `main` branch.
60+
4. Commit your changes including a descriptive message
61+
5. Create a pull request with your changes.
62+
6. The pull request will be reviewed by the repo maintainers. If you need to make further changes, make additional commits to keep commit history. When the PR is merged, commits will be squashed.
63+
64+
## Bug Reports
65+
66+
If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/stackit-cli/issues/new).
67+
68+
To ensure we can provide the best support to your issue, follow these guidelines:
69+
70+
1. Go through the existing issues to check if your issue has already been reported.
71+
2. Make sure you are using the latest version of the provider, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug.
72+
3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the provider, which operating system you are using and the corresponding version.
73+
4. Include in your issue the steps to reproduce it, along with code snippets and/or information about your specific use case. This will make the support process much easier and efficient.

‎LICENSE

Whitespace-only changes.

‎Makefile

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
ROOT_DIR ?= $(shell git rev-parse --show-toplevel)
2+
SCRIPTS_BASE ?= $(ROOT_DIR)/scripts
3+
GOLANG_CI_YAML_PATH ?= ${ROOT_DIR}/golang-ci.yaml
4+
GOLANG_CI_ARGS ?= --allow-parallel-runners --timeout=5m --config=${GOLANG_CI_YAML_PATH}
5+
6+
# Build
7+
build:
8+
@go build -o ./bin/stackit
9+
10+
# Setup and tool initialization tasks
11+
project-help:
12+
@$(SCRIPTS_BASE)/project.sh help
13+
14+
project-tools:
15+
@$(SCRIPTS_BASE)/project.sh tools
16+
17+
# Lint
18+
lint-golangci-lint:
19+
@echo "Linting with golangci-lint"
20+
@golangci-lint run ${GOLANG_CI_ARGS}
21+
22+
lint: lint-golangci-lint
23+
24+
# Test
25+
test:
26+
@echo "Running tests for the CLI application"
27+
@go test ./... -count=1
28+
29+
# Generate docs
30+
generate-docs:
31+
@echo "Generating docs..."
32+
@go run $(SCRIPTS_BASE)/generate.go

‎NOTICE.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
STACKIT CLI
2+
Copyright 2024 Schwarz IT GmBH & Co. KG

0 commit comments

Comments
 (0)