DOCSEARCHbyAlgolia
Submit Docs

Jenkins Operator

repository·master·Indexed 20 days ago

https://github.com/jenkinsci/kubernetes-operator

A Kubernetes-native operator designed to manage Jenkins instances using declarative Configuration as Code (CasC) and immutable principles. It automates the lifecycle of Jenkins controllers, providing built-in support for backups, plugin management, and integration with the Jenkins kubernetes-plugin.

Tokens
82.9K
Snippets
208
Records
350
Agent score
67%

What's inside jenkins-operator

  1. What is Docsy?

    master

    Docsy is a theme for the Hugo static site generator, specifically designed for technical documentation sets. It incorporates documentation best practices to help users set up reliable sites quickly.

    Key Characteristics:

    • Built on Hugo: Docsy provides the theme and templates, but Hugo is responsible for the actual generation of HTML files from Markdown or HTML source files.
    • Scalability: It is optimized for medium to large documentation sets (typically 20+ pages) that include various content types like tutorials, reference documentation, blog posts, and community pages.
    • Not a Hosting Provider: Docsy does not host your source files or deploy your site. You must manage your own source (e.g., via GitHub, GitLab, or BitBucket) and choose a deployment method (e.g., Netlify).

  2. What is the Jenkins Operator?

    master

    The Jenkins Operator is a Kubernetes Native Operator designed to manage Jenkins operations on Kubernetes. It is built with a focus on immutability and declarative Configuration as Code (CasC).

    Key features provided out of the box include:

  3. What is Docsy and how does it help?

    master

    Docsy is a pre-configured Hugo theme designed specifically for creating technical documentation sites. It provides the structural and UI components necessary for a professional documentation set, allowing developers to focus on content rather than site architecture.

    Key features provided by Docsy include:

    • Optimized Page Layouts: Specialized layouts for navigation, page menus, headers, landing pages, blog snippets, and feedback links.
    • Autogenerated Navigation: Automatically builds site menus based on your folder structure.
    • Language Switchers: Leverages Hugo's multi-language support for internationalization.
    • Feedback & Contribution Links: Built-in pathways for users to file issues, edit docs, or join community channels (Slack, Twitter, etc.).
    • Custom Shortcodes: Reusable HTML snippets for creating alerts, image boxes, and landing page blocks.
    • Tool Integrations: Built-in support for GitHub (in-page repo links), Google Analytics, and Google Custom Search.

  5. Understand the JenkinsStatus observed state

    master

    The JenkinsStatus object (part of the Jenkins CR) provides information about the observed state of a Jenkins instance. It tracks the lifecycle of the provisioning process, backup status, and configuration progress.

    Key fields include:

    • operatorVersion: The version of the operator managing this resource.
    • provisionStartTime: When the Jenkins master pod was created.
    • baseConfigurationCompletedTime: When the base configuration phase finished.
    • userConfigurationCompletedTime: When the user configuration phase finished.
    • lastBackup, pendingBackup, restoredBackup: Unsigned 64-bit integers tracking backup numbers.
    • backupDoneBeforePodDeletion: Boolean indicating if a backup was successfully made before the pod was deleted.
    • userAndPasswordHash: A SHA256 hash of the user and password.
    • createdSeedJobs: A list of seed job IDs already created in Jenkins.
    • appliedGroovyScripts: A list of all Groovy scripts applied by the operator.

  6. Understand JenkinsStatus and AppliedGroovyScript

    master

    The status field in the Jenkins resource provides information about the observed state of the Jenkins instance. One of the components of the status is AppliedGroovyScript, which tracks the Groovy scripts currently applied by the operator.

    AppliedGroovyScript Fields

    • configurationType: The type of configuration applied (base-groovy, user-groovy, or user-casc).
    • source: The name of the source where the Groovy script is located.
    • name: The name of the Groovy script.
    • hash: A hash representing the Groovy script and the secrets it utilizes, used to detect changes.

  7. Cross-namespace RBAC for Jenkins Operator

    master

    To allow an Operator in namespace A to manage resources in namespace B, you must create a Role and RoleBinding in namespace B. The RoleBinding in namespace B must explicitly point to the ServiceAccount in namespace A.

    Example pattern for namespace jenkins (target) and jenkins-operator (source):

    In the jenkins namespace, the RoleBinding should look like this:

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: jenkins-operator
subjects:
  - kind: ServiceAccount
    name: jenkins-operator
    namespace: jenkins-operator
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: jenkins-operator

  8. RBAC requirements for cross-namespace Jenkins Operator

    master

    When the Operator is in a separate namespace from Jenkins, the following RBAC configuration is required:

    1. In the Operator Namespace (jenkins-operator):

      • A ServiceAccount named jenkins-operator.
      • A Role for leader election (accessing configmaps and leases in coordination.k8s.io).
      • A Role named jenkins-operator with permissions to manage apps, jenkins.io, build.openshift.io, and core Kubernetes resources (pods, secrets, etc.).
      • A RoleBinding linking the jenkins-operator ServiceAccount to the jenkins-operator Role.

    2. In the Jenkins Namespace (jenkins):

      • A Role named jenkins-operator with the same broad permissions as described above to allow the Operator to manage resources within this namespace.
      • A RoleBinding that maps the ServiceAccount from the other namespace (jenkins-operator) to the Role in the current namespace (jenkins).

    Crucial RoleBinding detail for the Jenkins namespace:

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: jenkins-operator
subjects:
  - kind: ServiceAccount
    name: jenkins-operator
    namespace: jenkins-operator # The namespace where the Operator actually lives
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: jenkins-operator

  10. Understand restricted Jenkins controller volumeMounts

    master

    To maintain an immutable GitOps state, the Operator manages several volumeMounts for the Jenkins controller pod. You cannot overwrite these specific volumes; attempting to do so will result in an Operator error.

    The following volumeMounts are managed by the Operator and are non-configurable:

    • jenkins-home (mounts an emptyDir volume to ensure an ephemeral home directory)
    • scripts
    • init-configuration
    • operator-credentials

  11. Understanding JENKINS_HOME and persistence

    master

    The Jenkins Operator is designed for Jenkins to remain ephemeral to support scalability, smooth extension, and errorless backups.

    Note: There is no supported way to change JENKINS_HOME from a standard volume to a Persistent Volume (PV).

    Best Practice: All Jenkins configurations should be treated as volatile. Instead of relying on persistent storage for configuration, keep all configurations in a Version Control System (VCS).

  12. How the Jenkins Operator handles Azure AKS environment variables

    master

    Azure Kubernetes Service (AKS) automatically injects several environment variables into every pod, including:

    • KUBERNETES_PORT_443_TCP_ADDR
    • KUBERNETES_PORT
    • KUBERNETES_PORT_443_TCP
    • KUBERNETES_SERVICE_HOST

    To prevent infinite restart loops, the Jenkins Operator is designed to ignore these specific environment variables when performing its reconciliation loop. When the operator checks if a Jenkins pod's environment has changed, it omits these AKS-injected keys so that the presence of these managed variables does not trigger an unnecessary pod restart.

    - name: KUBERNETES_PORT_443_TCP_ADDR
  value:
- name: KUBERNETES_PORT
  value: tcp://
- name: KUBERNETES_PORT_443_TCP
  value: tcp://
- name: KUBERNETES_SERVICE_HOST
  value: