Config Repository

1. Concept
2. Repository content
3. Setting up the repository
   1. Gerrit
      • Prerequisites
      • Configuring Gerrit
      • Configuring the Zuul connection
   2. GitLab
      • Configuring the Zuul connection
4. Next Steps

Concept

Note

If you are already familiar with the config repository in Software Factory, you can skip this section and go straight to setting up the repository.

In Software Factory, Zuul and Nodepool's configurations are stored in a special git repository called the config repository. Zuul is also pre-configured to run the following CI pipelines and jobs against changes on this repository, in a reserved tenant (internal):

Pipeline	When	Jobs
check	A change is opened for review on the config repository	config-check
gate	A change on the config repository is scheduled for merging, before merging	config-check
post	After a change is merged	config-update

The internal tenant configuration is stored in a hidden git repository and managed solely by the SF-Operator. Below you can find more details about the default jobs running against the config repository:

Job name	Description
config-check	runs zuul-admin tenant-conf-check and nodepool config-validate to check the service configurations for errors
config-update	applies the new configurations and reconfigures the services as needed

This setup enables GitOps workflows on the configuration of your Zuul-based CI infrastructure.

The config repository is expected to follow a specific file structure for the automation to work properly. Please refer to the user documentation to learn more about the expected repository file structure and its usage.

Any other file or folder will be ignored.

Setting up the repository

As of the current version of the SF-Operator, Gerrit and GitLab are the only supported hosting options for the config repository.

Note

You can follow the developer's documentation to deploy a test Gerrit instance if needed.

Hosting on Gerrit

Prerequisites on Gerrit

1. Make sure the deployment and the Gerrit host can communicate, especially via Gerrit's SSH port (usually TCP/29418).
2. Make sure you can create accounts on the Gerrit host, or at least set their SSH public key.
3. Make sure you can create a project on the Gerrit host, or at least modify its configuration.

Configuring Gerrit

Gerrit Bot account

Zuul needs a bot account on Gerrit with SSH access to be able to subscribe to events and merge changes to the config repository.

The SF-Operator automatically creates an SSH key pair that can be used by such bot accounts, and stores it in a secret called zuul-ssh-key.

You can create the Zuul bot account on Gerrit with this convenient one-liner (assuming your deployment is installed in the sf namespace):

kubectl get secret zuul-ssh-key -n sf -o jsonpath={.data.pub} | base64 -d | ssh -p29418 <gerrit_host> gerrit create-account --ssh-key - --full-name Zuul --email zuul@example.com zuul

Then add the bot account to the Service Users group:

ssh -p29418 <gerrit_host> gerrit set-members --add zuul@example.com "Service Users"

Repository ACLs and Labels

Note

Access controls and labels management with Gerrit is out of the scope of this documentation. Please refer to Gerrit's documentation for further details, for example here for ACLs or here for labels.

The repository must be set with specific ACLs to allow Zuul to interact with it:

[access "refs/heads/*"]
label-Verified = -2..+2 group Service Users
submit = group Service Users

Zuul triggers events based on specific labels, so these must be configured as well.

Here are the required labels to define in the repository's Access settings (meta/config) on Gerrit:

[label "Code-Review"]
    function = MaxWithBlock
    defaultValue = 0
    copyMinScore = true
    copyAllScoresOnTrivialRebase = true
    value = -2 Do not submit
    value = "-1 I would prefer that you didn't submit this"
    value = 0 No score
    value = +1 Looks good to me, but someone else must approve
    value = +2 Looks good to me (core reviewer)
    copyAllScoresIfNoCodeChange = true
[label "Verified"]
    value = -2 Fails
    value = "-1 Doesn't seem to work"
    value = 0 No score
    value = +1 Works for me
    value = +2 Verified
[label "Workflow"]
    value = -1 Work in progress
    value = 0 Ready for reviews
    value = +1 Approved

For further information check the Gerrit section in Zuul's documentation.

Configuring the Gerrit Zuul connection

In order for Zuul to start listening to Gerrit events, add a gerritconn property in your deployed SoftwareFactory's Spec. Edit the spec with:

kubectl edit sf my-sf

[...]
spec:
  zuul:
    gerritconns:
      - name: gerrit
        username: zuul # (1)
        hostname: <gerrit_ssh_hostname>
        puburl: "<gerrit_url>"
[...]

1. The username is the name of the bot account that was set up in the previous section.

You can check the CRD's OpenAPI schema for specification details.

At that step you can continue the setting by configuring the location of the config repository.

Hosting on GitLab

Zuul needs:

• an API token to communicate with the GitLab's API
• a WebHook token in order to authenticate the WebHook's payloads sent by the GitLab instance.

It is advised to request a bot account to your GitLab admin, especially if Zuul must act on repositories spread across multiple Gitlab project groups. However if all repositories are located inside the same project's group then a simple group's token is sufficient.

Please refer to the upstream's Zuul documentation for more information about the GitLab's driver and how to define an API Token and WebHook token.

Note

The WebHook URL to configure on the project or on the project's group setting must be https://<fqdn>/zuul/api/connection/<zuul-connection-name>/payload

The gate pipeline defined for the config repository workflow relies in the gateit label for the pipeline trigger rule. Thus, a GitLab label named gateit must be defined in the Settings the config repository.

Configuring the Gitlab Zuul connection

To setup the zuul's connection to the GitLab instance, first you need a Secret resource (eg. named gitlab-com-secret) to store the API and WebHook tokens. The Secret's scheme is a follow:

kind: Secret
apiVersion: v1
metadata:
  name: gitlab-conn-secret
  namespace: sf
type: Opaque
data:
  api_token: <api-token-in-base64>
  webhook_token: <web-hook-token-in-base64>

This Secret resource must be applied to the same Namespace than the SoftwareFactory resource.

Then, edit the SoftwareFactory's CR:

kubectl edit sf my-sf
[...]
spec:
    zuul:
      gitlabconns:
        - name: <zuul-connection-name>
          server: gitlab.com
          baseurl: https://gitlab.com
          secrets: gitlab-conn-secret
[...]

At that step you can continue the setting by configuring the location of the config repository.

Set the config repository location

Specify the config repository location (adapt according to your connection/reposiory name and location):

kubectl edit sf my-sf
[...]
spec:
  config-location:
    base-url: "<gerrit_url>"
    name: <config repository name>
    zuul-connection-name: gerrit
[...]

Wait for the 'my-sf' resource to become READY:

kubectl get sf my-sf -o jsonpath='{.status}'

{"observedGeneration":1,"ready":true}

Once the resource is ready, the config repository will appear listed in the internal tenant's projects page at https://<FQDN>/zuul/t/internal/projects .

Next Steps

You may now want to configure connection secrets for nodepool providers (kubeconfig, clouds.yaml).

How to be an administrator in Internal Tenant

As said in the Concept section, SF-Operator manages a hidden git repository which defines and sets the internal tenant.

This tenant has an admin-rules definition, setting the admin-internal group as the tenant administrator.

To be an internal administrator, just set a authorization-rule named admin-internal in the config project defined at Set the config repository location