https://github.com/gridscale/gscloud
The official command-line interface for the gridscale API
https://github.com/gridscale/gscloud
command-line kubernetes
Last synced: 2 months ago
JSON representation
The official command-line interface for the gridscale API
- Host: GitHub
- URL: https://github.com/gridscale/gscloud
- Owner: gridscale
- License: mit
- Created: 2020-01-07T14:30:29.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-09-30T05:18:03.000Z (3 months ago)
- Last Synced: 2025-10-11T04:53:49.184Z (3 months ago)
- Topics: command-line, kubernetes
- Language: Go
- Homepage: https://gridscale.io/
- Size: 6.11 MB
- Stars: 17
- Watchers: 9
- Forks: 7
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Authors: AUTHORS.md
Awesome Lists containing this project
README
# gscloud
gscloud is a command-line tool that lets you manage your virtual infrastructure on [gridscale.io](https://gridscale.io).
gscloud is written in Go, so everything you need is just the gscloud binary. Compile it all by yourself or get the official release from the [release page](https://github.com/gridscale/gscloud/releases).
## Examples
See [examples](docs/examples.md) to get some first impressions.
## Installation
### Official releases for Windows, macOS, Linux, FreeBSD
Download packaged binaries from the [releases page](https://github.com/gridscale/gscloud/releases).
### OpenBSD
*TODO*
### Build from source
See [here](docs/source.md) on how to build gscloud from source.
## Configuration
You can use `gscloud make-config` to generate a new config file. Make sure to add your user ID and API token here.
Default locations:
- Linux: `$XDG_CONFIG_HOME/gridscale/config.yaml` or `$HOME/.config/gridscale/config.yaml`
- Mac: `~/Library/Application Support/gridscale/config.yaml`
- Windows: `%APPDATA%` or `"C:\\Users\\%USER%\\AppData\\Roaming"`
Example config:
```yml
projects:
- name: default
userId: 2727b9ab-65ff-4d1e-af5e-d08d682bd1fa
token: 6eb139b3b6515515a6f358d3a635e9b38f05935782602d4fd5c1b5716af54526
- name: liveaccount
userId: 2727b9ab-65ff-4d1e-af5e-d08d682bd1fa
token: 6eb139b3b6515515a6f358d3a635e9b38f05935782602d4fd5c1b5716af54526
url: https://api.gridscale.io
```
You can specify a custom location for the config file by using the `--config` flag, which
allows you to keep multiple configs per project or environment. For example:
```shelld
gscloud --config production.yml info
gscloud --config staging.yml info
```
Following environment variables can also be used instead of config file:
- `GRIDSCALE_UUID` - corresponds to `userId`
- `GRIDSCALE_TOKEN` - corresponds to `token`
- `GRIDSCALE_URL` - corresponds to `url`
**Note**: If the config file and the environment variables are used at the same time, the config file will be ignored and the environment variables will be used.
## Kubernetes
You can use gscloud to retrieve the kubeconfig of your managed Kubernetes cluster via
`gscloud kubernetes cluster save-kubeconfig --credential-plugin --cluster `
That way, gscloud will use the gridscale credentials configured in your gscloud
configuration to obtain a kubeconfig for your cluster and add that as a new context to your
`~/.kube/config`.
If you execute the command with `--credential-plugin`, as given in the example above, gscloud
will register itself as the credential plugin for the context and thereby automatically renew
the kubeconfig for you, once it has expired. If you do not pass in `--credential-plugin`, the
certificate will expire and can be renewed by running gscloud manually again.
When using gscloud in the context of a pipeline, the use of `--credential-plugin` is discouraged,
as it can lead to colliding kubeconfig renewals, unless gscloud's cache directory is persisted
across steps as an artifact.
## Exit codes
gscloud returns zero exit code on success, non-zero on failure. Following exit codes map to these failure modes:
1. The requested command failed.
2. Reading the configuration file failed.
3. The configuration could not be parsed.
4. The project specified does not exist in the configuration file.
## Shell completions
Generate shell completion scripts for zsh and bash.
* bash
```shell
$ gscloud completion bash >> ~/.bash_profile
```
* zsh
```shell
$ gscloud completion zsh >> ~/.zshrc
```
## Install man-pages
Generate man-pages and install them. Example:
```shell
$ sudo gscloud manpage /usr/local/share/man/man1/
```
## Contributing
Please create an [issue](https://github.com/gridscale/gscloud/issues) if you have questions, want to start a discussion, or want to start work on something.
[Pull requests](https://github.com/gridscale/gscloud/pulls) are always welcome. Make sure to create an issue first to signal others that you are working on something. Also make sure to take a look at the [Development Notes](docs/development.md).
Have fun!