GitLab Pipelines Integration
General
The GitLabPipelinesIntegration is designed to connect your GitLab instance with Puzl.
One integration scopes one team or department within your organization and enables its owner or maintainer to set up and manage runners for executing their pipeline jobs.
Puzl account owner (administrator) creates integrations in their Puzl root namespace, which can be found in Puzl dashboard after account creation.
metadata section
The metadata section is used to uniquely identify objects and to provide other information that is not directly tied to a resource's configuration.
Namespace defines the space within which each GitLabPipelinesIntegration name must be unique.
Each GitLabPipelinesIntegration name must be unique, within a namespace. The name must contain only lower-case letters, digits and dashes.
More Details
In this section, we've described only two fields that are necessary and sufficient for users on Puzl.
For a more in-depth explanation of metadata and its various fields, refer to the official Kubernetes documentation.
spec section
The section defines the desired state of the object. It describes the characteristics you want the resource to have: its configuration, settings, and data.
| Path: | spec.gitlabUrl |
Designates the URL of your GitLab instance. If you use GitLab.com service, you should pass https://gitlab.com in this field.
spec.resources
Defines the settings for managing resources of pipeline jobs.
spec.resources.persistentStorage
Configuration of pipeline job persistent data storage and cache.
| Default: | 30 |
| Path: | spec.resources.persistentStorage.cacheRetentionTime |
Specifies the duration in days for retaining cached data in the pipeline job's storage. The value is applied for each GitLab Runner within this integration.
This value determines how many days items in /cache directory remain available in the bucket before being automatically purged to free up space.
spec.serviceAccountPermissions
Contains capabilities of the Integration Service Account, which may be utilized for managing GitLab runners.
Access to the Integration Service Account may be granted to maintainer or owner of a specific GitLab group or project, allowing them to register and manage runners. The best practice of using Integration Service Account is to manage GitLab runners via CI/CD, following the typical GitOps approach. By default, Integration Service Account has limited permissions, allowing access to GitLabRunnerClaim and GitLabRunner resources only.
| Path: | spec.serviceAccountPermissions.readPipelineNamespaceSecrets |
If true, the Service Account is granted read permissions to all Secret resources in the Pipeline Namespace.
These Secrets contain credentials, such as those for remote Pipeline Data Storage access over S3 protocol, and the environment variables of the pipeline jobs.
| Path: | spec.serviceAccountPermissions.manageClaimNamespaceSecrets |
If true, the Service Account receives full access to manage all the credentials, stored as Secret resources within the Claim Namespace.
These Secrets might contain GitLab access tokens and the access tokens of the Integration Service Account itself. This setting carries significant security implications. Typically, while maintainers or owners of a specific GitLab group or project can manage GitLab runners using GitLabRunnerClaim resource, they might be restricted from using their own GitLab access tokens for runner registration, as per the admin's discretion. Enabling this setting allows these maintainers or owners to use GitLab access tokens issued by their own, giving them full autonomy over the process within the confines of the GitLab scope available to them.
| Path: | spec.runnerNamespaceRef |
The internal platform reference to the namespace where the runners of this integration will be set up.
This is crucial to ensure that runners for a specific integration are housed in a dedicated namespace, ensuring full isolation and security.
| Path: | spec.claimNamespaceRef |
Reference to the namespace where the GitLabRunnerClaim resources will be created.
This namespace is where users request runners, ensuring a clear separation between administration scope (Integration) and operation scope (Runner Claims). The access to this namespace can be granted to maintainers using serviceAccountRef.
spec.serviceAccountRef
Reference to a ServiceAccount that has been granted with the limited permissions for managing the claim namespace only.
| Path: | spec.serviceAccountRef.namespace |
Namespace where the referenced ServiceAccount is located.
status section
The section provides information about the current state of the object. It is populated by the platform and is used to inform users about the state of the resource, whether it's currently operational, and additional metadata like timestamps.
| Default: | Pending |
| Path: | status.phase |
Represents the high-level summary of the current status of the resource.
status.conditions[]
Conditions are designed based on Kubernetes API conventions. Conditions represent the logical states that the resource has passed through.
| Path: | status.conditions[].lastTransitionTime |
The last time the condition transitioned from one status to another.
| Path: | status.conditions[].observedGeneration |
The value of metadata.generation when the condition has been transited last time.
| Path: | status.conditions[].message |
A human-readable message indicating details about the transition.
| Path: | status.conditions[].reason |
A one-word, CamelCase reason caused the transition of the resource to this condition.
| Path: | status.conditions[].status |
The current status of the condition. Can be one of: True, False, or Unknown.