Initial commit

.github/actions/build/action.yaml

@@ -0,0 +1,16 @@
+name: Build
+description: "Build pipeline"
+inputs:
+  go-version:
+    description: "Go version to install"
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Install Go ${{ inputs.go-version }}
+      uses: actions/setup-go@v4
+      with:
+        go-version: ${{ inputs.go-version }}
+    - name: Install project tools and dependencies
+      shell: bash
+      run: make project-tools

.github/workflows/ci.yaml

@@ -0,0 +1,22 @@
+name: CI Workflow
+
+on: [pull_request, workflow_dispatch]
+
+env:
+  GO_VERSION: "1.21"
+
+jobs:
+  main:
+    name: CI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build
+        uses: ./.github/actions/build
+        with:
+          go-version: ${{ env.GO_VERSION }}
+      - name: Lint
+        run: make lint
+      - name: Test
+        run: make test

.github/workflows/release.yaml

@@ -0,0 +1,34 @@
+# STACKIT CLI release workflow.
+name: Release
+
+# This GitHub action creates a release when a tag that matches the pattern
+# "v*" (e.g. v0.1.0) is created.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+# Releases need permissions to read and write the repository contents.
+# GitHub considers creating releases and uploading assets as writing contents.
+permissions:
+  contents: write
+
+jobs:
+  goreleaser:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Allow goreleaser to access older tag information.
+          fetch-depth: 0
+      - uses: actions/setup-go@v4
+        with:
+          go-version-file: "go.mod"
+          cache: true
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v5
+        with:
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.CLI_RELEASE }}

.gitignore

@@ -0,0 +1,9 @@
+# Binaries
+bin/
+dist/
+
+# IDE
+.vscode
+
+# OS generated files
+.DS_Store

.goreleaser.yaml

@@ -0,0 +1,76 @@
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - id: linux-builds
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+    binary: "stackit"
+
+  - id: windows-builds
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - windows
+    binary: "stackit"
+
+  - id: macos-builds
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - darwin
+    binary: "stackit"
+
+archives:
+  - format: tar.gz
+    # This name template makes the OS and Arch compatible with the results of `uname`
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- title .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    format_overrides:
+      - goos: windows
+        format: zip
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"
+
+nfpms:
+  - id: linux-packages
+    # IDs of the builds for which to create packages for
+    builds:
+      - linux-builds
+    vendor: STACKIT
+    homepage: https://github.com/stackitcloud/stackit-cli
+    maintainer: STACKIT <[email protected]>
+    description: A command-line interface to manage STACKIT resources.
+    license: Apache 2.0
+    formats:
+      - deb
+      - rpm
+
+brews:
+  - name: stackit-cli
+    repository:
+      owner: stackitcloud
+      name: homebrew-tap
+    commit_author:
+      name: CLI Release Bot
+      email: [email protected]
+    homepage: "https://github.com/stackitcloud/stackit-cli"
+    description: "A command-line interface to manage STACKIT resources."
+    license: "Apache-2.0"
+    # If set to auto, the release will not be uploaded to the homebrew tap repo
+    # if the tag has a prerelease indicator (e.g. v0.0.1-alpha1)
+    # Not setting it for now to test with a prerelease tag
+    # skip_upload: auto

AUTHENTICATION.md

@@ -0,0 +1,101 @@
+# Authentication Guide
+
+This document describes how you can configure authentication for the STACKIT CLI.
+
+## Service account
+
+You can use a [service account](https://docs.stackit.cloud/stackit/en/service-accounts-134415819.html) to authenticate to the STACKIT CLI.
+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:
+
+```bash
+$ ./bin/stackit auth activate-service-account
+```
+
+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.
+
+### Overview
+
+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:
+
+- Key flow (recommended)
+- Token flow
+
+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:
+
+1. Explicitly provided credentials, e.g. by using the flag `--service-account-key-path`
+2. Environment variable, e.g. by setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
+3. Credentials file
+
+   The CLI will check the credentials file located in the path defined by the `STACKIT_CREDENTIALS_PATH` env var, if specified,
+   or in `$HOME/.stackit/credentials.json` as a fallback.
+   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:
+
+   ```json
+   {
+     "STACKIT_SERVICE_ACCOUNT_TOKEN": "foo_token",
+     "STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json"
+   }
+   ```
+
+### Key flow
+
+    The following instructions assume that you have created a service account and assigned it the necessary permissions, e.g. `project.owner`.
+
+To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it.
+
+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.
+
+**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).
+
+To configure the key flow, follow this steps:
+
+1.  Create a service account key:
+
+- In the CLI, run `stackit service-account key create --email <SERVICE_ACCOUNT_EMAIL>`
+- 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)
+
+2.  Save the content of the service account key by copying it and saving it in a JSON file.
+
+The expected format of the service account key is a **json** with the following structure:
+
+```json
+{
+  "id": "uuid",
+  "publicKey": "public key",
+  "createdAt": "2023-08-24T14:15:22Z",
+  "validUntil": "2023-08-24T14:15:22Z",
+  "keyType": "USER_MANAGED",
+  "keyOrigin": "USER_PROVIDED",
+  "keyAlgorithm": "RSA_2048",
+  "active": true,
+  "credentials": {
+    "kid": "string",
+    "iss": "[email protected]",
+    "sub": "uuid",
+    "aud": "string",
+    (optional) "privateKey": "private key when generated by the SA service"
+  }
+}
+```
+
+3. Configure the service account key for authentication in the CLI by following one of the alternatives below:
+
+   - using the flag `--service-account-key-path`
+   - setting the environment variable `STACKIT_SERVICE_ACCOUNT_KEY_PATH`
+   - setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` in the credentials file (see above)
+
+> **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:
+>
+> - using the flag `--private-key-path`
+> - setting the environment variable `STACKIT_PRIVATE_KEY_PATH`
+> - setting `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above)
+
+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.
+
+### Token flow
+
+Using this flow is less secure since the token is long-lived. You can provide the token in several ways:
+
+1. Providing the flag `--service-account-token`
+2. Setting the environment variable `STACKIT_SERVICE_ACCOUNT_TOKEN`
+3. Setting `STACKIT_SERVICE_ACCOUNT_TOKEN` in the credentials file (see above)

CONTRIBUTION.md

@@ -0,0 +1,73 @@
+# Contribute to the STACKIT CLI
+
+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.
+
+## Table of contents
+
+- [Developer Guide](#developer-guide)
+- [Code Contributions](#code-contributions)
+- [Bug Reports](#bug-reports)
+
+## Developer Guide
+
+### Repository structure
+
+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.
+
+### Getting started
+
+Check the [Authentication](README.md#authentication) section on the README.
+
+#### Useful Make commands
+
+These commands can be executed from the project root:
+
+- `make project-tools`: install the required dependencies
+- `make build`: compiles the CLI and saves the binary under _./bin/stackit_
+- `make lint`: lint the code and examples
+- `make generate-docs`: generates Markdown documentation for every command
+- `make test`: run unit tests
+
+#### Local development
+
+To test your changes, you can either:
+
+1. Build the application locally by running:
+
+   ```bash
+   $ go build -o ./bin/stackit
+   ```
+
+   To use the application from the root of the repository, you can run:
+
+   ```bash
+   $ ./bin/stackit [group] [subgroup] [command] [flags]
+   ```
+
+2. Skip building and run the Go application directly using:
+
+   ```bash
+   $ go run . [group] [subgroup] [command] [flags]
+   ```
+
+## Code Contributions (Coming soon to GitHub!)
+
+To make your contribution, follow these steps:
+
+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.
+2. Fork the repo.
+3. Make your changes in a branch that is up-to-date with the original repo's `main` branch.
+4. Commit your changes including a descriptive message
+5. Create a pull request with your changes.
+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.
+
+## Bug Reports (Coming soon to GitHub!)
+
+If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/stackit-cli/issues/new).
+
+To ensure we can provide the best support to your issue, follow these guidelines:
+
+1. Go through the existing issues to check if your issue has already been reported.
+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.
+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.
+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.

Makefile

@@ -0,0 +1,32 @@
+ROOT_DIR              ?= $(shell git rev-parse --show-toplevel)
+SCRIPTS_BASE          ?= $(ROOT_DIR)/scripts
+GOLANG_CI_YAML_PATH ?= ${ROOT_DIR}/golang-ci.yaml
+GOLANG_CI_ARGS ?= --allow-parallel-runners --timeout=5m --config=${GOLANG_CI_YAML_PATH}
+
+# Build
+build:
+	@go build -o ./bin/stackit   
+
+# Setup and tool initialization tasks
+project-help:
+	@$(SCRIPTS_BASE)/project.sh help
+
+project-tools:
+	@$(SCRIPTS_BASE)/project.sh tools
+
+# Lint
+lint-golangci-lint:
+	@echo "Linting with golangci-lint"
+	@golangci-lint run ${GOLANG_CI_ARGS}
+
+lint: lint-golangci-lint
+
+# Test
+test:
+	@echo "Running tests for the CLI application"
+	@go test ./... -count=1
+
+# Generate docs
+generate-docs:
+	@echo "Generating docs..."
+	@go run $(SCRIPTS_BASE)/generate.go

NOTICE.txt

@@ -0,0 +1,2 @@
+STACKIT CLI
+Copyright 2024 Schwarz IT GmBH & Co. KG