CLI¶

We provide a command to perform various actions related to the management of Software Factory deployments, beyond what can be defined in a custom resource manifest.

Installing the CLI
Global Flags
Configuration File
Subcommands
Dev
Init
Nodepool
Operator
SF
Zuul
- create auth-token
- create client-config

Installing the CLI¶

To build the CLI, assuming you are at the root directory of the sf-operator repository:

go install

Then the CLI can be used with:

sf-operator [GLOBAL FLAGS] [ARGS] [SUBCOMMAND FLAGS]...

Global Flags¶

These flags apply to every subcommand.

Argument	Type	Description	Optional	Default
-n, --namespace	string	The namespace on which to perform actions	Dependent	-
-k, --kube-context	string	The cluster context on which to operate	Dependent	-
-d, --fqdn	string	The FQDN of the deployment (if no manifest is provided)	Yes	sfop.me
-C, --config	string	Path to the CLI configuration file	Yes	-
-c, --context	string	Context to use in the configuration file. Defaults to the "default-context" value in the config file if set, or the first available context	Yes	Dependent

Configuration File¶

The CLI supports using a configuration file to keep track of commonly used parameters and flags. The configuration file supports several contexts if you are working on several distinct Software Factory deployments (for example, a dev instance and a production instance).

Structure¶

---
contexts:
  # the name of the context
  dev:
    # ALL FIELDS OPTIONAL
    # ---
    # the path to a local copy of the Software Factory's config repository
    config-repository-path: /path/to/config-repo
    # the path to the manifest defining the Software Factory deployment
    manifest-file: /path/to/manifest
    # specify whether the deployment was applied via an operator (standalone = false) or via the `apply` subcommand of the
    # CLI (standalone = true)
    standalone: false
    # the cluster's namespace on which to perform actions
    namespace: <namespace>
    # the kube context to use to perform actions, in case you have several contexts
    kube-context: <kube context>
    # the FQDN of the deployment if no manifest file is provided. Used mostly to interact with services' APIs.
    fqdn: <fqdn>
    # Developer settings
    development:
      # the path to a local copy of the ansible-microshift-role repository
      # (https://github.com/openstack-k8s-operators/ansible-microshift-role)
      ansible-microshift-role-path: /path/to/ansible-microshift-role/repository
      # path to a local copy of the sf-operator repository
      sf-operator-repository-path: /path/to/sf-operator/repository
      # Microshift deployment settings (used by the Ansible deployment playbook)
      microshift:
        host: microshift.dev
        user: cloud-user
        # The pull secret is required, see the MicroShift section of the developer documentation
        openshift-pull-secret: |
          PULL_SECRET
        # extra configuration settings
        # how much space to allocate for persistent volume storage
        disk-file-size: 30G
      # Settings used when running the test suite locally
      tests:
        # where to check out/create the demo repositories used by tests
        demo-repos-path: deploy/
        # Ansible extra variables to pass to the testing playbooks
        extra-vars:
          key1: value1
          key2: value2
    # SF components settings
    components:
      nodepool:
        # path to the local copy of the `clouds.yaml` file used by the Openstack provider
        clouds-file: /path/to/clouds-file
        # path to the local copy of the `kube.config` file used by the K8s-based providers
        kube-file: /path/to/kube-file
default-context: dev

Subcommands¶

Dev¶

The dev subcommand can be used to manage a development environment and run tests.

cloneAsAdmin¶

Warning

A Gerrit instance must have been deployed with the create gerrit command first.

Clone a given repository hosted on the Gerrit instance, as the admin user. You can then proceed to create patches and run them through CI with git review. If the repository already exists locally, refresh it by resetting the remotes and performing a hard reset on the master branch.

sf-operator [GLOBAL FLAGS] cloneAsAdmin REPO [DEST] [flags]

Flags:

Argument	Type	Description	Optional	Default
--verify	boolean	Enforce SSL validation	yes	False

create demo-env¶

Create a Gerrit instance if needed, then clone and populate demo repositories that will set up a demo tenant.

Warning

This command will also install the operator's Custom Resource Definitions, so you need to run make manifests beforehand.

sf-operator [GLOBAL FLAGS] dev create demo-env [FLAGS]

Flags:

Argument	Type	Description	Optional	Default
--keep-tenant-config	boolean	Do not update the demo tenant configuration	yes	False
--repos-path	string	Where to clone the demo repositories	yes	./deploy/

create gerrit¶

Create a Gerrit stateful set that can be used to host repositories and code reviews with a SF deployment.

sf-operator [GLOBAL FLAGS] dev create gerrit

To use this Gerrit instance with your Software Factory deployment, add the following to your SF manifest:

[...]
spec:
  zuul:
    gerritconns:
      - name: gerrit
        username: zuul
        hostname: gerrit-sshd
        puburl: "https://gerrit.<FQDN>"

where <FQDN> is your domain name.

To host the config repository on this Gerrit instance, add the following to your SF manifest:

[...]
spec:
  config-location:
    base-url: "http://gerrit-httpd/"
    name: config
    zuul-connection-name: gerrit

create microshift¶

Install and configure a MicroShift instance on a given server. This instance can then be used to host, develop and test the operator.

Warning

ansible-playbook is required to run this command. Make sure it is installed on your system.

sf-operator [GLOBAL FLAGS] dev create microshift [FLAGS]

Warning

The "Local Setup" step of the installation requires local root access to install required development dependencies. If you don't want to automate this process, run the command with the --dry-run --skip-deploy --skip-post-install flags to inspect the generated playbook and figure out what you need.

Flags:

Argument	Type	Description	Optional	Default
--dry-run	boolean	Create the playbooks but do not run them.	yes	False
--skip-local-setup	boolean	Do not install requirements and dependencies locally	yes	False
--skip-deploy	boolean	Do not install and start MicroShift on the target host	yes	False
--skip-post-install	boolean	Do not install operator dependencies, pre-configure namespaces	yes	False

create standalone-sf¶

Deploy a "standalone" Software Factory. In standalone mode, you do not need to install or run the operator controller within your cluster. You do not need to install the Software Factory CRDs as well. The CLI will take a Software Factory manifest as input and deploy all the required services as a one-shot.

sf-operator [GLOBAL FLAGS] dev create standalone-sf --cr /path/to/manifest

Flags:

Argument	Type	Description	Optional	Default
--cr	string	The path to the custom resource to apply	No	If a config file is used and the flag not provided, will default to the context's `manifest-file` if set

run-tests¶

Run the playbook for a given test suite. Extra variables can be specified.

sf-operator [GLOBAL FLAGS] dev run-tests {olm,standalone,upgrade} [FLAGS]

Flags:

Argument	Type	Description	Optional	Default
--extra-var	string	Set an extra variable in the form `key=value` to pass to the test playbook. Repeatable	Yes	-
--v	boolean	Run playbook in verbose mode	Yes	false
--vvv	boolean	Run playbook in debug mode	Yes	false
--prepare-demo-env	boolean	Prepare a demo environment before running the test suite (see dev create demo-env)	Yes	false

wipe gerrit¶

Delete a Gerrit instance deployed with dev create gerrit.

sf-operator [GLOBAL FLAGS] dev wipe gerrit [--rm-data]

Flags:

Argument	Type	Description	Optional	Default
--rm-data	boolean	Also delete persistent data (repositories, reviews)	yes	False

getImagesSecurityIssues¶

To get a report of Security Issues reported by quay.io for container images used by the sf-operator run: dev getImagesSecurityIssues. This command helps to decide if we need to rebuild container images to benefit last security fixes from the base OS.

sf-operator dev getImagesSecurityIssues

wipe sf¶

Delete a deployed Software Factory and optionally delete the data (PVC) and the sf-operator deployment.

sf-operator [GLOBAL FLAGS] dev wipe sf [FLAGS]

Flags:

Argument	Type	Description	Optional	Default
--rm-data	boolean	Delete also persistent data	yes	False
--rm-operator	boolean	[sf] Delete also the operator installation	yes	False

Init¶

The init subcommand can be used to initialize a CLI configuration file, or a sample manifest for deploying Software Factory.

config¶

Generate a simple CLI configuration tree with one context. It is up to you to save it to a chosen file, and to edit it to suit your requirements.

sf-operator [GLOBAL FLAGS] init config [--dev] > /path/to/sfcli.config

Flags:

Argument	Type	Description	Optional	Default
--dev	boolean	Include development-related configuration parameters	yes	False

manifest¶

Generate a basic Software Factory manifest that can be used to deploy a Software Factory. It is up to you to save it a chosen file, edit it as you see fit and then apply it to your cluster.

sf-operator [GLOBAL FLAGS] init manifest [FLAGS] > /path/to/sf.yaml

Flags:

Argument	Type	Description	Optional	Default
--connection	string, repeatable	Include connection. The first connection of the list will be assumed to host the deployment's config repository	yes	gerrit
--full	boolean	Include optional fields in the manifest, for a more fine-tuned deployment	yes	False
--with-auth	boolean	Include OIDC authentication configuration	yes	False
--with-builder	boolean	Include nodepool builder configuration	yes	False

Nodepool¶

The nodepool subcommand can be used to interact with the Nodepool component of a Software Factory deployment.

configure providers-secrets¶

Set or update Nodepool's providers secrets (OpenStack's clouds.yaml and Kubernetes/OpenShift's kube.config).

Warning

At least one of the --kube or --clouds flags must be provided.

sf-operator [GLOBAL FLAGS] nodepool configure providers-secrets [--kube /path/to/kube.config --clouds /path/to/clouds.yaml]

Flags:

Argument	Type	Description	Optional	Default
--kube	string	The file from which to read nodepool's kube.config	yes	-
--clouds	string	The file from which to read nodepool's clouds.yaml	yes	-

create openshiftpods-namespace¶

Create and set up a dedicated namespace on a cluster, so that nodepool can spawn pods with the openshiftpods driver.

Note

See this section in the deployment documentation for more details.

sf-operator [GLOBAL FLAGS] nodepool create openshiftpods-namespace [FLAGS]

Flags:

Argument	Type	Description	Optional	Default
--nodepool-context	string	The kube context to use to set up the namespace	yes	default context set with `kubectl`
--nodepool-namespace	string	The namespace to set up	yes	nodepool
--show-config-template	boolean	Display a nodepool configuration snippet that can be used to enable an openshiftpods provider using the created namespace	yes	false
--skip-providers-secrets	boolean	Do not update or create nodepool's providers secrets after setting up the namespace	yes	false

get builder-ssh-key¶

The Nodepool builder component should be used with at least one image-builder companion machine. It must have the capablility to connect via SSH to the builder machine(s). In order to do so, you need to install the builder's SSH public key as an authorized key on the builder machine(s). This subcommand fetches that key and can save it to a speficied file path.

sf-operator [GLOBAL FLAGS] nodepool get builder-ssh-key [--pubkey /path/to/key]

Flags:

Argument	Type	Description	Optional	Default
--pubkey	string	The destination file where to save the builder's public key	yes	-

get providers-secrets¶

Get the currently set providers secrets (OpenStack's clouds.yaml and Kubernetes/OpenShift's kube.config) and optionally write the secrets to a local file.

Danger

The local files will be overwritten with the downloaded contents without warning!

sf-operator [GLOBAL FLAGS] nodepool get providers-secrets [--kube /path/to/kube.config --clouds /path/to/clouds.yaml]

Flags:

Argument	Type	Description	Optional	Default
--kube	string	The destination file where to save nodepool's kube.config	yes	-
--clouds	string	The destination file where to save nodepool's clouds.yaml	yes	-

Operator¶

To start the operator controller locally, run:

sf-operator operator [FLAGS]

Flags:

Argument	Type	Description	Optional	Default
--metrics-bind-address	string	The address the metric endpoint binds to.	Yes	:8080
--health-probe-bind-address	string	The address the probe endpoint binds to.	Yes	:8081
--leader-elect	boolean	Enable leader election for controller manager.	Yes	false

SF¶

The following subcommands can be used to manage a Software Factory deployment and its lifecycle.

backup¶

The backup subcommand lets you dump a Software Factory's most important files for safekeeping.

To create a backup located in /tmp/backup directory, run the following command:

sf-operator SF backup --namespace sf --backup_dir /tmp/backup

Flags:

Argument	Type	Description	Optional	Default
--backup_dir	string	The path to the backup directory	no	-

The backup is composed of:

some relevant Secrets located in the deployment's namespace
the Zuul's SQL database
the Zuul's project's keys as exported by zuul-admin export-keys

The backup directory content could be compressed and stored safely in a backup system.

bootstrap-tenant¶

Initialize a Zuul tenant's config repository with boilerplate code that define standard pipelines:

"check" for pre-commit validation
"gate" for approved commits gating
"post for post-commit actions

it also includes a boilerplate job and pre-run playbook.

sf-operator SF bootstrap-tenant /path/to/tenant-config-repo [FLAGS]

Flags:

Argument	Type	Description	Optional	Default
--connection	string	The name of the Zuul connection to use for pipelines	No	-
--driver	string	The driver used by the Zuul connection. Supported drivers: gerrit, gitlab	No	-

configure TLS¶

The configure TLS subcommand can be used to inject a pre-existing set of certificates to secure the HTTPS endpoints of a Software Factory deployment.

sf-operator [GLOBAL FLAGS] SF configure TLS --CA /path/to/CA --cert /path/to/cert --key /path/to/privatekey

Flags:

Argument	Type	Description	Optional	Default
--CA	string	The path to the PEM-encoded Certificate Authority file	no	-
--cert	string	The path to the domain certificate file	no	-
--key	string	The path to the private key file	no	-

restore¶

Warning

The command requires to to have kubectl binary installed in the system

The restore subcommand lets you restore a backup created with the backup command.

For example:

sf-operator SF restore --namespace sf --backup_dir my_backup_dir

Available flags:

Argument	Type	Description	Optional	Default
--backup_dir	string	The path to the backup directory to restore	yes	-

Zuul¶

These subcommands can be used to interact with the Zuul component of a deployment.

create auth-token¶

The create auth-token subcommand can be used to create a custom authentication token that can be used with the zuul-client CLI utility.

sf-operator [GLOBAL FLAGS] zuul create auth-token [FLAGS]

Flags:

Argument	Type	Description	Optional	Default
--auth-config	string	The authentication configuration to use	yes	zuul_client
--tenant	string	The tenant on which to grant admin access	no	-
--user	string	a username, used for audit purposes in Zuul's access logs	yes	"John Doe"
--expiry	int	How long in seconds the authentication token should be valid for	yes	3600

create client-config¶

The create client-config generates a configuration file that can be used with the zuul-client CLI utility against the Software Factory deployment.

Warning

The command provisions authentication tokens that grant admin access to all tenants. It is recommended to review and eventually edit the output of the command before forwarding it to third parties.

sf-operator [GLOBAL FLAGS] zuul create client-config [FLAGS] > zuul-client.conf

Flags:

Argument	Type	Description	Optional	Default
--auth-config	string	The authentication configuration to use	yes	zuul_client
--tenant	string	The tenant on which to grant admin access	no	-
--user	string	a username, used for audit purposes in Zuul's access logs	yes	"John Doe"
--expiry	int	How long in seconds the authentication token should be valid for	yes	3600
--insecure	boolean	skip SSL validation when connecting to Zuul	yes	False