This repository holds the source code for the Red Hat Porfolio Marketing Gitea Operator. The operator can be recreated by following the steps in https://github.com/redhat-cop/openshift-lab-origin/blob/master/OpenShift4/Building_Ansible_Operator_for_Gitea.adoc.
The V2 operator can now be installed into its own namespace gitea-operator
instead of just openshift-operators
.
-
You can create the operator by simply applying the YAML files from the Github repository
oc apply -k https://github.com/rhpds/gitea-operator/OLMDeploy
-
This installs the operator cluster wide - which means you (or your users) can greate instances of
Gitea
in any project on the cluster. See below for examples of how to create Gitea instances.
-
Create a new project for your Gitea instance:
oc new-project gitea
-
All following examples can be combined. For example you can have a Gitea installation with self-managed PostgreSQL database, with e-mail integration, selecting specific storage classes for the PVCs, an Admin user created and self-provisioning turned off.
The Gitea Operator can set up a PostgreSQL database alongside the Gitea Pod. This is the default deployment.
To deploy a simple Gitea instance:
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: simple-gitea spec: giteaImageTag: 1.20.0 giteaVolumeSize: 4Gi giteaSsl: true postgresqlVolumeSize: 4Gi
Note that you can specify specific properties for postgresqlServiceName
, postgresqlDatabaseName
, postgresqlUser
and postgresqlPassword
. If you do however you must also specify the relevant properties for Gitea to connect to the database and they must match the PostgreSQL properties: giteaPostgresqlServiceName
, giteaPostgresqlDatabaseName
, giteaPostgresqlUser
and giteaPostgresqlPassword
To deploy a simple Gitea instance using OpenShift Container Storage (if the storage class ocs-storagecluster-ceph-rbd
is not the default storage class):
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: simple-gitea-ocs spec: giteaImageTag: latest giteaVolumeSize: 4Gi giteaVolumeStorageClass: ocs-storagecluster-ceph-rbd giteaSsl: true postgresqlVolumeSize: 4Gi postgresqlVolumeStorageClass: ocs-storagecluster-ceph-rbd
The Operator can create an Admin User in the Gitea instance. If a Admin User ID is specified you can specify a password for the admin user as well. If no password is specified a password is generated with a certain length. The length of the generated password can be set via the password length variable.
If an Admin user has been created then you can set the variable giteaDisableRegistration: false
. This will disable user self-registration - only the admin user will be able to create other users on Gitea.
The operator will report the status of the admin user creation as well as the user password in the fields .status.adminSetupComplete: true
and .status.adminPassword
.
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-with-admin spec: giteaSsl: true giteaAdminUser: opentlc-mgr giteaAdminEmail: [email protected] giteaAdminPassword: "" giteaAdminPasswordLength: 32
The operator can use a password from the admin user that has been pre-created in a secret. The secret must be in the same namespace as the gitea instance - and the key for the admin password must be adminPassword
.
-
Create a secret with the password:
oc create secret generic gitea-admin-password --from-literal=adminPassword=myPassw0rd
-
Tell the operator to use the password from the secret:
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-with-admin spec: giteaSsl: true giteaAdminUser: opentlc-mgr giteaAdminEmail: [email protected] giteaAdminPasswordSecretName: gitea-admin-password
It may be useful to hide the admin password from the status
section of the Gitea custom resource. In that case set the variable giteaAdminPasswordExpose: false
. For compatibility reasons the default for that variable is true
which means that whatever password has been set for the admin user will be visible in status.adminPassword
.
The Operator can also create regular users in the Gitea instance. It is a requirement that an admin user is also being created.
The operator can create a single user - or a number of users based on a username template.
You can specify a common password for all regular users. If no password is specified a password is generated with a certain length. The length of the generated password can be set via the password length variable.
If an users have been created then you can set the variable giteaDisableRegistration: false
. This will disable user self-registration - only the admin user will be able to create additional users on Gitea.
The operator will report the status of the user creation as well as the user password in the fields .status.userSetupComplete: true
and .status.userPassword
.
Create a single user, lab-user
with a generated password of length 16:
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-with-admin spec: giteaSsl: true giteaAdminUser: opentlc-mgr giteaAdminPassword: "" giteaAdminPasswordLength: 32 giteaAdminEmail: [email protected] giteaCreateUsers: true giteaGenerateUserFormat: lab-user giteaUserNumber: 1 giteaUserPasswordLength: 16
Create a three users, student1
, student2
and student3
with password openshift
:
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-with-users spec: giteaSsl: true giteaAdminUser: opentlc-mgr giteaAdminPassword: "" giteaAdminPasswordLength: 32 giteaAdminEmail: [email protected] giteaCreateUsers: true giteaGenerateUserFormat: "student%d" giteaUserNumber: 3 giteaUserPassword: openshift
The operator can use a password for the created users that has been pre-created in a secret. The secret must be in the same namespace as the gitea instance - and the key for the user password must be userPassword
.
-
Create a secret with the password:
oc create secret generic gitea-user-password --from-literal=userPassword=myPassw0rd
-
Tell the operator to use the password from the secret (this example also generates a new 16 character password for the admin user):
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-with-users spec: giteaSsl: true giteaAdminUser: opentlc-mgr giteaAdminEmail: [email protected] giteaAdminPassword: "" giteaAdminPasswordLength: 16 giteaCreateUsers: true giteaGenerateUserFormat: "student%d" giteaUserNumber: 3 giteaUserPasswordSecretName: gitea-user-password
It may be useful to hide the user password from the status
section of the Gitea custom resource. In that case set the variable giteaUserPasswordExpose: false
. For compatibility reasons the default for that variable is true
which means that whatever password has been set for the users will be visible in status.userPassword
.
If users are being created it is also possible to seed all users with repositories from another github (compatible) source. Every user will get the same repositories in their account. You can specify the source URL of the repository, the name of the migrated repository in Gitea and if the migrated repository should be a private repository or not.
If the migration was successful the operator sets the field .status.repoMigrationComplete: true
.
Create 2 users lab-user-1
and lab-user-2
and migrate two repositories from GitHub to Gitea for each user:
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-with-repositories spec: giteaSsl: true giteaAdminUser: opentlc-mgr giteaAdminPassword: "" giteaAdminPasswordLength: 32 giteaAdminEmail: [email protected] giteaCreateUsers: true giteaGenerateUserFormat: "lab-user-%d" giteaUserNumber: 2 giteaUserPassword: openshift giteaMigrateRepositories: true giteaRepositoriesList: - repo: https://github.com/repository1.git name: repository1 private: false - repo: https://github.com/repository2.git name: another-repository private: true
See https://docs.gitea.io/en-us/email-setup for more information on how to set up e-mail services with Gitea.
-
Set the variable
giteaMailerEnabled: true
. If this is set to true then the othergiteaMailer*
variables need to be set as well. If the e-mail account you are using uses two-factor authentication (for example GMail) you may need to create an app-specific password to be used.Once e-mail is enabled you can use the variables
giteaRegisterEmailConfirm
andgiteaEnableNotifyMail
to turn on e-mail verification and notification.Example for GMail--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-with-email spec: giteaMailerEnabled: true giteaMailerFrom: [email protected] giteaMailerProtocol: smtps giteaMailerHost: smtp.gmail.com giteaMailerPort: 465 giteaMailerUser: [email protected] giteaMailerPassword: gmail-user-app-specific-password giteaMailerHeloHostname: example.com giteaRegisterEmailConfirm: true giteaEnableNotifyMail: true
If you want to manage your PostgreSQL database separately from the Gitea pod then you can deploy it first. You can either use the OpenShift template or you can use a PostgreSQL operator to manage your database.
-
Create a PostgreSQL database from the OpenShift template:
oc new-app postgresql-persistent \ --param DATABASE_SERVICE_NAME=postgresql-gitea \ --param POSTGRESQL_USER=gitea_user \ --param POSTGRESQL_PASSWORD=gitea_pass \ --param POSTGRESQL_DATABASE=gitea \ --param VOLUME_CAPACITY=10Gi
NoteYou can not specify a storage class when using the OpenShift template. If you need a specific storage class make that storage class the default storage class before creating the database. You can switch back to another default storage class once the persistent volume has been created. -
Create a Gitea instance. When using a self-managed database you must set
postgresqlSetup: false
and specify connection information to the database.
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-unmanaged-db spec: postgresqlSetup: false giteaPostgresqlServiceName: postgresql-gitea giteaPostgresqlDatabaseName: gitea giteaPostgresqlUser: gitea_user giteaPostgresqlPassword: gitea_pass giteaVolumeSize: 10Gi
A rather advanced use case is to create the app.ini
configuration for Gitea yourself rather than having the operator create it.
Usually the operator generates the app.ini
configuration file based on the content of the variables in the Gitea custom resource. However not every single configuration option for Gitea is exposed as Gitea variables. Maybe because they are rather uncommon or because they only got added to a Gitea version that got released after the operator was built.
One use case could be enabling ssh
cloning capability for the Gitea repository.
Another use case could be setting up OAuth2 authorization for the repository.
The suggested approach is this:
-
Set up a Gitea instance with all variables that are available.
-
Wait until the Gitea instance is running
-
Extract (save) the ConfigMap that has been created (usually in
<gitea-name>-config
)oc get configmap gitea-config -n gitea -o yaml >$HOME/configmap.yaml
-
Edit the file
app.ini
in the configmap as desired (the file name always must beapp.ini
). -
Delete the Gitea config.
Now you can re-create the configuration from scratch. You can have the Gitea operator create the PostgreSQL database - but of course you must specify a user name and password for the PostgreSQL database that matches what you will provide in your app.ini
config map.
-
Create the project
-
Determine what the
hostname
of your Gitea installation will be. This hostname must match in the configmap’sapp.ini
file and in the parametergiteaHostname
(which must be provided in case an external configmap is provided) -
Create the ConfigMap (from file or otherwise) making sure the URLs match the desired hostname and the database connectivity matches your PostgreSQL database (either pre-setup of setup by the operator)
Example[...] [database] DB_TYPE = postgres HOST = postgresql-gitea:5432 NAME = giteadb USER = gitea_user PASSWD = gitea_pass SSL_MODE = disable [...] [server] ROOT_URL = https://gitea-gitea.apps.cluster-hyper.hyper.dev.redhatworkshops.io SSH_DOMAIN = gitea-gitea.apps.cluster-hyper.hyper.dev.redhatworkshops.io DOMAIN = gitea-gitea.apps.cluster-hyper.hyper.dev.redhatworkshops.io [...]
-
Create Gitea making sure the
giteaHostname
is part of thespec
.
--- apiVersion: pfe.rhpds.com/v1 kind: Gitea metadata: name: gitea-ext-config spec: postgresqlSetup: true giteaPostgresqlServiceName: postgresql-gitea giteaPostgresqlDatabaseName: giteadb giteaPostgresqlUser: gitea_user giteaPostgresqlPassword: gitea_pass giteaImageTag: 1.20.0 giteaVolumeSize: 4Gi giteaAdminUser: wkadmin giteaAdminPassword: "" giteaAdminUserPasswordLength: 16 giteaConfigMapName: custom-gitea-config giteaSsl: true giteaHostname: gitea.apps.cluster-hyper.hyper.dev.redhatworkshops.io
Below is a list and description of all possible parameters that can be set for the Gitea
custom resource.
postgresqlSetup: description: 'Set up a PostgreSQL database alongside the Gitea instance. Default is true. If set to false the values for giteaPostgresqlServiceName, giteaPostgresqlDatabaseName, giteaPostgresqlUser and giteaPostgresqlPassword need to be specified to connect to an existing PostgreSQL database. If set to true no values need to be specified for database name, database service, database user and database service.' type: boolean postgresqlServiceName: description: Name of the PostgreSQL database service. Default is 'postgresql-' followed by the name of the Gitea resource. type: string postgresqlDatabaseName: description: Name of the PostgreSQL Database to be created. Default is 'giteadb'. type: string postgresqlUser: description: Username to be created in the PostgreSQL database. Default is 'giteauser'. type: string postgresqlPassword: description: Password to be used for the PostgreSQL database user. Default is 'giteapassword'. type: string postgresqlVolumeSize: description: Size of the persistent volume claim for the PostgreSQL database. Default is '4Gi'. type: string postgresqlVolumeStorageClass: description: Storage Class to be used for the PostgreSQL persistent volume claim. Default is empty - which will create a PVC using the currently available default storage class on the cluster. type: string postgresqlImage: description: Container image for the PostgreSQL database. Default is 'registry.redhat.io/rhel8/postgresql-12'. type: string postgresqlImageTag: description: Image tag for the PostgreSQL container image. Default is 'latest'. type: string postgresqlImagePullPolicy: description: Pull policy for the PostgreSQL container image. Default is 'IfNotPresent'. type: string postgresqlMemoryRequest: description: Memory request for the PostgreSQL database. Default is '512Mi'. type: string postgresqlMemoryLimit: description: Memory limit for the PostgreSQL database. Default is '512Mi'. type: string postgresqlCpuRequest: description: CPU request for the PostgreSQL database. Default is '200m'. type: object additionalProperties: anyOf: - type: integer - type: string pattern: "^(\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))))?$" x-kubernetes-int-or-string: true postgresqlCpuLimit: description: CPU limit for the PostgreSQL database. Default is '500m'. type: object additionalProperties: anyOf: - type: integer - type: string pattern: "^(\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))))?$" x-kubernetes-int-or-string: true giteaServiceName: description: Name of the Gitea Service to be deployed. Defaults to the name of the Gitea custom resource. type: string giteaSsl: description: Create an HTTPS terminated route for Gitea. Default is 'false' type: boolean giteaHostname: description: Specify the hostname for the Gitea Route. Default is ''. Make sure the route is reachable from outside the cluster. type: string giteaVolumeSize: description: Size of the persistent volume claim for Gitea. Default is '4Gi'. type: string giteaVolumeStorageClass: description: Storage Class to be used for the Gitea persistent volume claim. Default is empty - which will create a PVC using the currently available default storage class on the cluster. type: string giteaImage: description: Container image for Gitea. Default is 'quay.io/rhpds/gitea'. type: string giteaImageTag: description: Image tag for the Gitea container image. Default is 'latest'. type: string giteaImagePullPolicy: description: Pull policy for the Gitea container image. Default is 'IfNotPresent'. type: string giteaMemoryRequest: description: Memory request for Gitea. Default is '1Gi'. type: string giteaMemoryLimit: description: Memory limit for Gitea. Default is '1Gi'. type: string giteaCpuRequest: description: CPU request for Gitea. Default is '200m'. type: object additionalProperties: anyOf: - type: integer - type: string pattern: "^(\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))))?$" x-kubernetes-int-or-string: true giteaCpuLimit: description: CPU limit for Gitea. Default is '500m'. type: object additionalProperties: anyOf: - type: integer - type: string pattern: "^(\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\\\+|-)?(([0-9]+(\\\\.[0-9]*)?)|(\\\\.[0-9]+))))?$" x-kubernetes-int-or-string: true giteaPostgresqlServiceName: description: 'Name of the PostgreSQL service. Only required when PostgreSQL is not set up by the operator. Default: postgresql- followed by the Gitea resource name.' type: string giteaPostgresqlDatabaseName: description: 'Name of the PostgreSQL database. Only required when PostgreSQL is not set up by the operator. Default: giteadb' type: string giteaPostgresqlUser: description: 'Name of the PostgreSQL user. Only required when PostgreSQL is not set up by the operator. Default: giteauser' type: string giteaPostgresqlPassword: description: 'PostgreSQL password. Only required when PostgreSQL is not set up by the operator. Default: giteapassword' type: string giteaConfigMapName: description: Name of a config map in the same namespace as the Gitea custom resource. The config map must contain one file called app.ini to configure Gitea. If this variable is set then giteaHostname must also be set. giteaSsl should be set but will default to false. type: string giteaAdminUser: description: 'User ID for the Admin User to be created. If not specified no admin user will be created. Note that if giteaDisableRegistration is set to false and no admin user will be created you will not be able to create any users for Gitea. Default: ""' type: string giteaAdminPassword: description: 'Password for the Gitea admin user. If not specified or empty a random password will be created with length of giteaAdminPasswordLength random ASCII characters. Default: ""' type: string giteaAdminPasswordLength: description: 'If a giteaAdminUser is provided but no giteaAdminPassowrd is provided a random ASCII password with the length specified will be created. Default: 16' type: integer giteaAdminPasswordSecretName: description: Name of a secret containing the Gitea admin user's password in secret key adminPassword. If this variable is set it takes precedence over all other ways to specify/generate an admin password. type: string giteaAdminPasswordExpose: description: Expose the final Gitea admin password in the custom resource status section. Default is true for compatibility. Set to false to not show the password in the status section. type: boolean giteaAdminEmail: description: 'e-mail address for the Gitea Admin User. Default: "[email protected]"' type: string giteaCreateUsers: description: 'Create users in Gitea. Only possible if an admin user is also being created. Default: false' type: boolean giteaUserNumber: description: 'Number of users to create in Gitea. If 1 then only one user will be created with the username from giteaGenerateUserFormat. If more than one then users will be created according to the format in giteaGenerateUserFormat. Default: 2' type: integer giteaGenerateUserFormat: description: 'Format for user names to be created. This will be taken literally if only one user is to be created (e.g. lab-user). If more than one user is to be created the format needs to include a "%d" to set the user number. Default: "user%d"' type: string giteaUserPassword: description: 'Password for all created Gitea users. If not specified or empty a random password will be created with length of giteaUserPasswordLength random ASCII characters. Default: ""' type: string giteaUserPasswordLength: description: 'If a giteaCreateUsers is set but no giteaUserPassowrd is provided a random ASCII password with the length specified will be created. Default: 16' type: integer giteaUserEmailDomain: description: 'e-mail domain for the created Gitea users. Default: "example.com"' type: string giteaUserPasswordSecretName: description: Name of a secret containing the Gitea user common password in secret key userPassword. If this variable is set it takes precedence over all other ways to specify/generate a user password. type: string giteaUserPasswordExpose: description: Expose the common Gitea user password in the custom resource status section. Default is true for compatibility. Set to false to not show the password in the status section. type: boolean giteaMigrateRepositories: description: 'For created users migrate repositories from another location, e.g. GitHub. Default: false' type: boolean giteaRepositoriesList: description: 'List of repositories to be created. Each repository is an array of "repo: <source URL", "name: <name of migrated repository>" and "private: true | false". Default: []' type: array items: type: object properties: repo: description: 'Source repository URL to clone.' type: string name: description: 'Name of the repository in Gitea.' type: string private: description: 'Create private repository in Gitea.' type: boolean giteaHttpPort: description: 'Port for Gitea to listen on. Default: 3000' type: integer giteaSshPort: description: 'Port for Gitea to start an SSH server on. Default: 2022' type: integer giteaDisableSsh: description: 'Disable SSH for Gitea. Default: true' type: boolean giteaStartSshServer: description: 'Start SSH Server in the Gitea container. Default: false' type: boolean giteaStartLfsServer: description: 'Start LFS Server in the Gitea container. Default: false' type: boolean giteaDisableRegistration: description: 'Disable user self-registration. If this flag is set an Admin User should be specified to be created. Otherwise no users can be created at all. Default: false' type: boolean giteaEnableCaptcha: description: 'Display Captcha when users are registering a new account. No effect if giteaDisableRegistration is set to false. Default: false' type: boolean giteaAllowCreateOrganization: description: 'Allow users to create organizations in Gitea. Default: true' type: boolean giteaAllowLocalNetworkMigration: description: 'Allow migration of repositories hosted on local network IPs as defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291. Default: false' type: boolean giteaWebhookAllowedHostList: description: List of hosts that a web hook is allowed to call. See https://docs.gitea.com/next/administration/config-cheat-sheet#webhook-webhook for more details. Default is 'external,private'. type: string giteaWebhookSkipTlsVerify: description: Set to 'true' to skip validation of the webhook target URL certificate. Default is false. type: boolean giteaMailerEnabled: description: 'Enable e-mail integration for Gitea. If set to true the other giteaMailer* properties need to be provided. See https://docs.gitea.io/en-us/email-setup/ for example values. Default: false' type: boolean giteaMailerFrom: description: 'E-mail integration. FROM e-mail address to be used. Default: ""' type: string giteaMailerProtocol: description: 'Protocol of e-mail provider to be used. Default: smtps' type: string giteaMailerHost: description: 'Hostname of the e-mail server to be used. Default: ""' type: string giteaMailerPort: description: 'Port of the e-mail server to be used. Default: ""' type: integer giteaMailerUser: description: 'User ID on the e-mail server to use. Frequently the same as the value for giteaMailerFrom. Default: ""' type: string giteaMailerPassword: description: 'Password for the User ID on the e-mail server to be used. May need to be an app-specific password if two-factor authentication is enabled on the e-mail server. Default: ""' type: string giteaMailerHeloHostname: description: 'Helo Hostname for the e-mail server. Not required for all e-mail providers. Default: ""' type: string giteaRegisterEmailConfirm: description: 'Send e-mail confirmation to users when self-registering. Users must click a link to validate their e-mail address before the account gets created. Requires the mailer to be configured correctly. Default: false' type: boolean giteaEnableNotifyMail: description: 'Send e-mail notifications to users for various tasks in Gitea. Requires the mailer to be configured correctly. Default: false' type: boolean