{"id":18834007,"url":"https://github.com/jetstack/jsctl","last_synced_at":"2025-04-14T04:32:15.137Z","repository":{"id":58865857,"uuid":"534173032","full_name":"jetstack/jsctl","owner":"jetstack","description":"CLI tool for Jetstack Secure","archived":false,"fork":false,"pushed_at":"2023-09-18T16:11:35.000Z","size":840,"stargazers_count":2,"open_issues_count":12,"forks_count":4,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-03-27T18:55:20.084Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://platform.jetstack.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jetstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-08T11:06:14.000Z","updated_at":"2024-04-24T15:31:22.000Z","dependencies_parsed_at":"2023-02-17T21:46:12.227Z","dependency_job_id":null,"html_url":"https://github.com/jetstack/jsctl","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fjsctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fjsctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fjsctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jetstack%2Fjsctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jetstack","download_url":"https://codeload.github.com/jetstack/jsctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248821899,"owners_count":21166979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T02:06:13.121Z","updated_at":"2025-04-14T04:32:10.114Z","avatar_url":"https://github.com/jetstack.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jsctl\n\n**Note: currently this code can only be built and tested by those with access\nto Jetstack private repos. The process for community involvement has yet to be\ndetermined.**\n\njsctl is the command-line tool for interacting with the [Jetstack Secure Control Plane](https://platform.jetstack.io).\n\nIt can be used to configure a Kubernetes cluster with Jetstack Secure components and to create resources in Jetstack Secure control plane.\n\nSee [jsctl reference documentation](/docs/reference/jsctl.md) for all available commands or keep reading for common usage scenarios.\n\n## Getting Started\n\nObtain a binary for your os and architecture from the [releases page](https://github.com/jetstack/jsctl/releases) and\nplace it somewhere within your `PATH` environment variable.\n\nSome commands make modifications to the Kubernetes cluster specified as your current context within your kubeconfig\nfile. Ensure you're set up to use the correct cluster using the `kubectl config use-context` command. By default,\nthe kubeconfig is expected at `~/.kube/config` but it can be set via the `KUBECONFIG` environment variable or by\nproviding the path via the `--kubeconfig` flag for commands that interact with clusters.\n\n### Authentication\n\nTo authenticate, use the `jsctl auth login` command. It will open your default browser and navigate to the login screen.\n\nIn a non-interactive environment, or if the browser cannot be opened, it will print out a URL for you to visit:\n\n```shell\njsctl auth login\n\u003e Navigate to the URL below to login:\n\u003e https://auth.jetstack.io/authorize\n```\n\nOnce you have logged in, you should see a `Login Succeeded` message in your terminal. Check the browser window for any\nerrors.\n\nTo remove all authentication data from the host system, use the `jsctl auth logout` command.\n\n#### Unattended\n\nIf you need to log in using a non-interactive environment, you can use service account credentials instead. Either\nset the location of the credentials as the `JSCTL_CREDENTIALS` environment variable or provide the location via the\n`--credentials` flag when calling `jsctl auth login`.\n\n```shell\njsctl auth login --credentials /path/to/credentials.json\n```\n\n### Configure organization\n\nOnce authenticated, select your organization using the `jsctl config set` command. The organization you select will be\nused for subsequent commands\n\n```shell\njsctl config set organization my-organization\n\u003e Your organization has been changed to my-organization\n```\n\nYou can view which organizations you belong to using the `jsctl organizations list` command.\n\n### Clusters\n\n#### Connect Clusters\n\nOnce you've selected an organization, you can install the agent using the `jsctl clusters connect` command. This command\napplies the YAML required to install an agent in your cluster. This uses your current kubernetes context as the target\nfor the deployment.\n\n```shell\njsctl clusters connect my-cluster\n```\n\nOtherwise, you can write the output to a file and use it in your GitOps workflow:\n\n```shell\njsctl clusters connect --stdout my-cluster \u003e\u003e agent.yaml\n```\n\nSee [jsctl reference documentation](/docs/reference/jsctl_clusters.md) for additional cluster management options.\n\n### Operator\n\nJetstack Secure Operator can be used to set up a cluster with Jetstack Secure\ncomponents, see\n[documentation](https://platform.jetstack.io/documentation/reference/js-operator/about).\n\njsctl has a number of commands to make it easier to install and configure the\noperator, see [reference documentation](/docs/reference/jsctl_operator.md).\n\n#### Install the Operator\n\nTo install the Jetstack Operator, you can use the `jsctl operator deploy` command. It will apply the manifests required\nto run the operator directly to your current kubernetes context. You will need to have obtained your secret key file for\nauthenticating with the Jetstack container registry and provide it to the command via the `--credentials` flag.\n\n```shell\njsctl operator deploy --credentials /path/to/secret.json\n```\n\nTo just obtain the manifests, provide the `--stdout` flag:\n\n```shell\njsctl operator deploy --stdout --credentials /path/to/secret.json \u003e\u003e operator.yaml\n```\n\nBy default, it will install the latest version of the operator. You can specify a specific version using the `--version`\nflag:\n\n```shell\njsctl operator deploy --credentials /path/to/secret.json --version v0.0.1-alpha.0\n```\n\nTo view all available versions of the operator to install, you can use the `jsctl operator versions` command, which outputs\nthe versions in order from oldest to newest.\n\nSee [jsctl reference documentation](/docs/reference/jsctl_operator_deploy.md) for additional operator deployment options.\n\n#### Create an installation\n\n`jsctl` can be used to generate and/or apply configuration for the operator to create Jetstack Secure components.\n\nThis is an alternative to creating operator's configuration by hand.\n\nJetstack Secure Operator can be configured to create Jetstack Secure components via `Installation` custom resource, see [documentation](https://platform.jetstack.io/documentation/reference/js-operator/about).\n\nTo create an `Installation` resource with jsctl, you can use the `jsctl operator installations apply` command which will apply the generated config to cluster or output it as yaml if `--stdout` flag is passed.\n\n##### Generate base Installation resource\n\njsctl can be used as a quickstart config generator for operator's `Installation`\nresource for specific scenarios as an alternative to writing your own\n`Installation` resource from scratch.\n\n```shell\njsctl operator installations apply --stdout \u003e installation.yaml\n```\nThis command generates a base Installation resource that configures the operator to install cert-manager and [approver-policy](https://cert-manager.io/docs/projects/approver-policy/).\n\nTake a look at the generated config and see the [Jetstack Secure operator documentation](https://platform.jetstack.io/documentation/reference/js-operator/about) for how to configure additional resources like issuers.\n\nApply the installation to cluster when ready:\n\n```shell\nkubectl apply -f installation.yaml\n```\n##### Generate and apply Installation that configures Jetstack Secure components for Venafi TPP user\n\njsctl can be used to generate and/or apply operator configuration to set up a cluster with components relevant for Venafi TPP user.\n\n###### TPP issuer with static credentials\n\nCreate a file with Venafi connection details and credentials `connection.yaml`:\n\n```yaml\nmy-default-zone:\n  zone: \u003ctpp-zone\u003e\n  url: \u003ctpp-server-url\u003e\n  # access-token: \u003caccess-token could be used instead of username \u0026 password\u003e\n  username: \u003cyour-username\u003e\n  password: \u003cyour-password\u003e\n```\n\nRun:\n\n```shell\njsctl operator installations apply \\\n  --experimental-venafi-issuers=\"tpp:my-default-zone:foo\" \\\n  --experimental-venafi-connections-config ./connection.yaml\n```\n\nThis command will create and apply to cluster:\n\n- An `Installation` custom resource that will configure the operator to install cert-manager, [approver-policy](https://cert-manager.io/docs/projects/approver-policy/), a Venafi TPP `ClusterIssuer` named `foo` configured with the provided TPP URL and zone as well as an 'allow all' `CertificateRequestPolicy` for the ClusterIssuer and RBAC that allows cert-manager to use the policy\n\n- a `Secret` named `foo-jsctl` in `jetstack-secure` namespace with static credentials for `foo` `ClusterIssuer`.\n\n###### TPP issuer with access token managed by venafi-oauth-helper\nCreate a file with Venafi connection details and credentials `connection.yaml`:\n\n```yaml\nmy-default-zone:\n  zone: \u003ctpp-zone\u003e\n  url: \u003ctpp-server-url\u003e\n  username: \u003cyour-username\u003e\n  password: \u003cyour-password\u003e\n```\n\nNote that only username and password (not access token) can be used with venafi-oauth-helper.\n\nRun:\n\n```shell\njsctl operator installations apply \\\n  --venafi-oauth-helper \\\n  --experimental-venafi-issuers=\"tpp:my-default-zone:foo\" \\\n  --experimental-venafi-connections-config ./connection.yaml\n```\n\nThis command will create and apply to cluster:\n\n- An `Installation` custom resource that will configure the operator to install cert-manager, [approver-policy](https://cert-manager.io/docs/projects/approver-policy/), [venafi-oauth-helper](https://platform.jetstack.io/documentation/reference/venafi-oauth-helper/configuration), a Venafi TPP `ClusterIssuer` named `foo` configured with the provided TPP URL and zone as well as an 'allow all' `CertificateRequestPolicy` for the ClusterIssuer and RBAC that allows cert-manager to use the policy\n\n- a `foo-voh-bootstrap` `Secret` with the provided Venafi credentials that will be used as a bootstrap credentials by venafi-oauth-helper to create a dynamically refreshed access token for the `foo` `ClusterIssuer` (see [venafi-oauth-helper docs](https://platform.jetstack.io/documentation/reference/venafi-oauth-helper/configuration) for details)\n\n###### cert sync with cert-discovery-venafi\n\n[cert-discovery-venafi](https://platform.jetstack.io/documentation/reference/cert-discovery-venafi/configuration) can be used to sync certs in clusters to Venafi TPP.\n\nCreate a file with Venafi connection details and credentials `connections.yaml`:\n\n```yaml\nfoo-issuer-zone: # TPP zone for certs issued via `foo` ClusterIssuer (see below)\n  zone: \u003ctpp-zone\u003e\n  url: \u003ctpp-server-url\u003e\n  username: \u003cyour-username\u003e\n  password: \u003cyour-password\u003e\nsynced-certs-zone: # TPP zone where cert-discovery-venafi will sync other certs to\n  zone: \u003ctpp-zone\u003e\n  url: \u003ctpp-server-url\u003e\n  access-token: \u003caccess-token\u003e\n```\nNote that only username and password (not access token) can be used with venafi-oauth-helper whilst cert-discovery-venafi only accepts access token, so even if the two zones are the same, different connections with different sets of credentials are required.\n\nRun:\n\n```shell\njsctl operator installations apply \\\n  --venafi-oauth-helper \\\n  --experimental-venafi-issuers=\"tpp:foo-issuer-zone:foo\" \\\n  --experimental-cert-discovery-venafi-connection=\"synced-certs-zone\" \\\n  --cert-discovery-venafi \\\n  --experimental-venafi-connections-config ./connections.yaml\n```\n\nThis command will create and apply to cluster:\n\n- An `Installation` custom resource that will configure the operator to install cert-manager, [approver-policy](https://cert-manager.io/docs/projects/approver-policy/), [venafi-oauth-helper](https://platform.jetstack.io/documentation/reference/venafi-oauth-helper/configuration), [cert-discovery-venafi](https://platform.jetstack.io/documentation/reference/cert-discovery-venafi/configuration) configured with TPP URL and zone from `synced-certs-zone` Venafi connection, a Venafi TPP `ClusterIssuer` named `foo` configured with the provided TPP URL and zone  from 'foo-issuer-zone' as well as an 'allow all' `CertificateRequestPolicy` for the ClusterIssuer and RBAC that allows cert-manager to use the policy\n\n- a `foo-voh-bootstrap` `Secret` with the provided Venafi credentials that will be used as a bootstrap credentials by venafi-oauth-helper to create a dynamically refreshed access token for the `foo` `ClusterIssuer` (see [venafi-oauth-helper docs](https://platform.jetstack.io/documentation/reference/venafi-oauth-helper/configuration) for details)\n\n- a `Secret` named `access-token` in `jetstack-secure` namespace with the access token from `synced-certs-zone` Venafi connection that cert-discovery-venafi uses to authenticate\n\nSee [documenation](./docs/reference/jsctl_operator_installations_apply.md) for additional configuration options.\n\n### Users\n\n#### List users\n\nTo list all users in your organization, you can use the `jstcl users list` command.  You can provide the `--json` flag\nto produce the list as a JSON array. This could then be piped into a tool like `jq` for further processing.\n\n```shell\njsctl users list\n```\n\n#### Add Users\n\nTo add a user to your organization, you can use the `jsctl users add` command and provide their email address. By default,\nusers will be created as members. You can provide the `--admin` flag to create the user as an administrator of your\norganization.\n\n```shell\njsctl users add [--admin] test@example.com\n```\n\nYou can view the users within an organization using the `jsctl users list` command.\n\n#### Remove Users\n\nTo remove a user from your organization, you can use the `jsctl users remove` command and provide their email address.\n\n```shell\njsctl users remove test@example.com\n```\n\nYou will be prompted for confirmation for user removal. If the given response is anything except `y` or `Y` the removal\nis cancelled. If you do not want to confirm your choice, provide the `--force` flag:\n\n```shell\njsctl users remove --force test@example.com\n```\n\n\n## Development\n\n- This repository depends on the private https://github.com/jetstack/js-operator Go module.\n  To pull this module via Go you might need to set `GOPRIVATE` env var i.e `GOPRIVATE=\"github.com/jetstack/*\" go get -u`\n- `jsctl` writes configuration (current organization) to a local file, on UNIX the path will likely be `~/.config/jsctl/config.json`\n\n### Release process\n\nTo release a new version of `jsctl`:\n\n1. Create a new tag and push to upstream `main` branch\n\n2. Observe that `Release` Github Actions workflow runs and publishes a new Github release\n\n3. (If command line flags have changed) regenerate docs with `make docs-gen` locally, commmit and make a PR\n\n## Special Thanks\n\nWhen this project was made public, its commit history was wiped.\n\nWe thank these users for their contributions to `jsctl`:\n\n* [Irbe Krumina](https://github.com/irbekrm) - @irbekrm\n* [Charlie Egan](https://github.com/charlieegan3) - @charlieegan3\n* [David Bond](https://github.com/davidsbond) - @davidsbond\n* [Mathias Gees](https://github.com/MattiasGees) - @MattiasGees\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetstack%2Fjsctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjetstack%2Fjsctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjetstack%2Fjsctl/lists"}