Skip to content

Commit 1ca40b4

Browse files
git-hyagigit-hyagi
committed
update docs
1 parent 4d79a11 commit 1ca40b4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+3503
-25
lines changed

‎config/manifests/bases/pulp-operator.clusterserviceversion.yaml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1085,7 +1085,7 @@ spec:
10851085
Pulp is completely free and open-source!
10861086
10871087
* License: GPLv2+
1088-
* Documentation: [https://docs.pulpproject.org/](https://docs.pulpproject.org/)
1088+
* Documentation: [https://pulpproject.org/](https://pulpproject.org/)
10891089
* Source: [https://github.com/pulp/pulpcore/](https://github.com/pulp/pulpcore/)
10901090
10911091
For more information, check out the project website: [https://pulpproject.org](https://pulpproject.org)
@@ -1096,7 +1096,7 @@ spec:
10961096
10971097
Pulp Operator is under active development, with the goal to provide a scalable and robust cluster for Pulp 3.
10981098
1099-
<br>Pulp operator is manually built and [hosted on quay.io](https://quay.io/repository/pulp/pulp-operator). Read more about the container images [here](https://docs.pulpproject.org/pulp_operator/container/).
1099+
<br>Pulp operator is manually built and [hosted on quay.io](https://quay.io/repository/pulp/pulp-operator). Read more about the container images [here](https://pulpproject.org/pulp-oci-images/docs/admin/reference/available-images/single-process-images/).
11001100
11011101
## Custom Resource Definitions
11021102
Pulp Operator currently provides three different kinds of [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#custom-resources): Pulp, Pulp Backup and Pulp Restore.
@@ -1110,7 +1110,7 @@ spec:
11101110
11111111
## Get Help
11121112
1113-
Documentation: [https://docs.pulpproject.org/pulp_operator/](https://docs.pulpproject.org/pulp_operator/)
1113+
Documentation: [https://pulpproject.org/pulp_operator/](https://pulpproject.org/pulp_operator/)
11141114
11151115
Issue Tracker: [https://github.com/pulp/pulp-operator/issues](https://github.com/pulp/pulp-operator/issues)
11161116
@@ -1401,7 +1401,7 @@ spec:
14011401
- name: Pulp Project
14021402
url: https://pulpproject.org/
14031403
- name: Docs
1404-
url: https://docs.pulpproject.org/pulp_operator/
1404+
url: https://pulpproject.org/pulp_operator/
14051405
maintainers:
14061406
- email: pulp-list@redhat.com
14071407
name: Pulp Community

‎controllers/repo_manager/controller_test.go‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1255,24 +1255,3 @@ func objectGet[T client.Object](ctx context.Context, object T, objectName string
12551255
return true
12561256
}, timeout, interval).Should(BeTrue())
12571257
}
1258-
1259-
/*
1260-
// Alternative implementation without generics because i'm not sure if github runner is
1261-
// installed with golang 1.18+ and in case we need backward compatibility
1262-
// (keeping it just in case, but we should clean this up if not needed)
1263-
func objectUpdate(pulp any) {
1264-
var obj client.Object
1265-
switch objType := pulp.(type) {
1266-
case client.Object:
1267-
obj = objType
1268-
}
1269-
1270-
Eventually(func() bool {
1271-
if err := k8sClient.Update(ctx, obj); err != nil {
1272-
fmt.Println("Error trying to update pulp: ", err)
1273-
return false
1274-
}
1275-
return true
1276-
}, timeout, interval).Should(BeTrue())
1277-
}
1278-
*/

‎staging_docs/admin/guides/backup_and_restore/00-overview.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Overview of Backup/Restore Operations
2+
3+
4+
In addition to provisioning Pulp components, the Operator can also be used to backup and restore them.
5+
6+
!!! note
7+
Before starting a backup, make sure that the namespace has enough storage quota available.
8+
9+
## Backup
10+
The backup procedure creates a *manager* `Pod` which will be used to execute all the backup tasks:
11+
12+
* run a `pg_dump` (database dump) on Pulp's database
13+
* do a copy of the Pulp CR instance defined in `deployment_name`
14+
* do a copy of the `Secrets`
15+
* do a copy of `/var/lib/pulp` directory
16+
* delete the *manager* `Pod` to not consume resources
17+
18+
These data will be stored in a new PVC defined in PulpBackup CR (`backup_pvc` or `backup_storage_class`).
19+
20+
21+
!!! note
22+
The current version of the Operator does **not** execute backups of **external** PostgreSQL instances yet.
23+
24+
25+
!!! notes
26+
Considering that files stored in Object Storage (like `AWS S3` and/or `Azure Blob`) are not kept in `/var/lib/pulp` directory, they will **not** be copied. If you still need to do a backup of the artifacts stored in Object Storage, please, contact your cloud provider to check the procedure to do so.
27+
28+
29+
## Restore
30+
The restore procedure also creates a *manager* `Pod` to execute all the tasks:
31+
32+
* restore the `Secrets`
33+
* restore Pulp CR instance
34+
* restore Pulp database
35+
* restore `/var/lib/pulp` directory
36+
* delete the *manager* `Pod` to not consume resources
37+
38+
All data restored comes from the PVC defined in PulpRestore CR (`backup_pvc`).

‎staging_docs/admin/guides/backup_and_restore/01-config_and_run.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Configure and Run Backup/Restore
2+
3+
4+
All the configurations needed to run the backup or restore procedures are made through `PulpBackup` or `PulpRestore` CRs.
5+
6+
To get the list of fields available in each CR, check [`PulpBackupSpec`](/pulp_operator/backup/#pulpbackupspec) and [`PulpRestoreSpec`](/pulp_operator/restore/#pulprestorespec).
7+
8+
## Backup
9+
10+
To configure the backup controller, create a manifest file with the definition of [PulpBackup CR](/pulp_operator/backup/#pulpbackupspec).
11+
For example:
12+
```
13+
---
14+
apiVersion: repo-manager.pulpproject.org/v1beta2
15+
kind: PulpBackup
16+
metadata:
17+
name: pulpbackup-sample
18+
spec:
19+
deployment_name: pulp
20+
deployment_type: pulp
21+
backup_storage_class: standard
22+
admin_password_secret: example-pulp-admin-password
23+
postgres_configuration_secret: pulp-postgres-configuration
24+
```
25+
26+
In the above sample we defined:
27+
28+
* the name of `Pulp` instance (`deployment_name`), which can be gathered with:
29+
```
30+
$ kubectl get pulp
31+
NAME AGE
32+
pulp 3m30s
33+
```
34+
35+
* the type of deployment (`deployment_type`), in this case `pulp` (but could also be `galaxy` depending on the installation).
36+
* the name of `StorageClass` used to provision the `PVC` to store the backup data (`backup_storage_class`).
37+
* the name of the `Secret` with Pulp admin password (`admin_password_secret`), which can be get by:
38+
```
39+
$ kubectl get pulp pulp -ojsonpath='{.spec.admin_password_secret}{"\n"}'
40+
pulp-admin-password
41+
```
42+
43+
* the name of the `Secret` with PostgreSQL credentials and connection information (`postgres_configuration_secret`).
44+
45+
After finishing to configure the file, apply the configuration and the Operator will start the backup:
46+
```
47+
kubectl apply -f <backup_cr_file>.yaml
48+
```
49+
50+
51+
## Restore
52+
53+
54+
To configure the restore controller, create a manifest file with the definition of [PulpRestore CR](/pulp_operator/restore/#pulprestorespec).
55+
For example:
56+
```
57+
---
58+
apiVersion: repo-manager.pulpproject.org/v1beta2
59+
kind: PulpRestore
60+
metadata:
61+
name: pulprestore-sample
62+
spec:
63+
backup_name: pulpbackup-sample
64+
deployment_name: pulp
65+
```
66+
67+
In the above sample we defined:
68+
69+
* the name of `PulpBackup` instance (`backup_name`)
70+
* the name of `Pulp` instance (`deployment_name`). This should be the same defined in the `PulpBackup` CR.
71+
72+
After finishing to configure the file, apply the configuration and the Operator will start the restore:
73+
```
74+
kubectl apply -f <restore_cr_file>.yaml
75+
```
76+
77+
By default, the restore procedure will reprovision the environment with a single replica of each component. This is to make it easier to review the restore status and the environment health.
78+
It is also possible to restore with the same number of replicas running when the backup was made. To do so, just set the `keep_replicas` field to true, for example:
79+
```
80+
---
81+
apiVersion: repo-manager.pulpproject.org/v1beta2
82+
kind: PulpRestore
83+
metadata:
84+
name: pulprestore-sample
85+
spec:
86+
backup_name: pulpbackup-sample
87+
deployment_name: pulp
88+
keep_replicas: true
89+
```
90+
91+
92+
After finishing to restore the environment, the operator will create a `ConfigMap` called *`restore-lock`*. It is used to prevent a new controller reconciliation loop to run and override any data changed/created with the "old" data from backup.
93+
To allow the restore controller to run again, delete the *restore-lock* `ConfigMap`.

‎staging_docs/admin/guides/backup_and_restore/02-cronjob.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Schedule Backups
2+
3+
The current version of Pulp Operator does not provide a way to automate the periodic execution of the backups. The following steps can be used as **an example** of how to create a [k8s Cronjob](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/) to schedule the backup execution.
4+
5+
* create a configmap with the `PulpBackup CR` definition (check the [backup section](/pulp_operator/backup_and_restore/config_running/#backup) for more information on `PulpBackup CR` fields configuration):
6+
```yaml
7+
$ kubectl apply -f- <<EOF
8+
apiVersion: v1
9+
data:
10+
pulp_backup.yaml: |
11+
apiVersion: repo-manager.pulpproject.org/v1beta2
12+
kind: PulpBackup
13+
metadata:
14+
name: pulpbackup
15+
spec:
16+
deployment_name: pulp
17+
backup_storage_class: standard
18+
kind: ConfigMap
19+
metadata:
20+
name: pulpbackup-cr
21+
EOF
22+
```
23+
24+
* for this example, we will create a new `ServiceAccount` that will be used by `Cronjob` pods. It is not a required step, you can skip it if your environment already has a `ServiceAccount` with the permissions to modify `PulpBackup` resources:
25+
```yaml
26+
$ kubectl apply -f-<<EOF
27+
---
28+
apiVersion: v1
29+
kind: ServiceAccount
30+
metadata:
31+
name: pulpbackup
32+
---
33+
apiVersion: rbac.authorization.k8s.io/v1
34+
kind: Role
35+
metadata:
36+
name: pulpbackup
37+
rules:
38+
- apiGroups: ["repo-manager.pulpproject.org"]
39+
resources: ["pulpbackups"]
40+
verbs: ["get", "watch", "list","create","patch","update","delete"]
41+
---
42+
apiVersion: rbac.authorization.k8s.io/v1
43+
kind: RoleBinding
44+
metadata:
45+
name: pulpbackup
46+
subjects:
47+
- kind: ServiceAccount
48+
name: pulpbackup
49+
roleRef:
50+
kind: Role
51+
name: pulpbackup
52+
apiGroup: rbac.authorization.k8s.io
53+
EOF
54+
```
55+
56+
* create the `k8s Cronjob` to run the backups:
57+
```yaml
58+
$ kubectl apply -f-<<EOF
59+
apiVersion: batch/v1
60+
kind: CronJob
61+
metadata:
62+
name: pulpbackup
63+
spec:
64+
schedule: "00 2 * * *"
65+
successfulJobsHistoryLimit: 1
66+
failedJobsHistoryLimit: 1
67+
jobTemplate:
68+
spec:
69+
template:
70+
spec:
71+
containers:
72+
- name: bkp
73+
image: bitnami/kubectl:latest
74+
imagePullPolicy: IfNotPresent
75+
volumeMounts:
76+
- name: pulpbackup-cr
77+
mountPath: /tmp/pulp_backup.yaml
78+
subPath: pulp_backup.yaml
79+
command:
80+
- /bin/sh
81+
- -c
82+
args:
83+
- "kubectl apply -f /tmp/pulp_backup.yaml && kubectl wait --for condition=BackupComplete --timeout=600s -f /tmp/pulp_backup.yaml ; kubectl delete -f /tmp/pulp_backup.yaml"
84+
restartPolicy: Never
85+
serviceAccountName: pulpbackup
86+
volumes:
87+
- name: pulpbackup-cr
88+
configMap:
89+
name: pulpbackup-cr
90+
EOF
91+
```
92+
93+
In this example, the job:
94+
95+
* will be triggered every day at *2:00 AM* (`schedule: 00 2 * * *`)
96+
* will keep `1` successful and/or `1` failed job (`successfulJobsHistoryLimit: 1, failedJobsHistoryLimit: 1`)
97+
* will be considered failed if the backup does not finish in `10minutes` (`--timeout=600s`)
98+
* will run with the previously created *pulpbackup* `ServiceAccount` (`serviceAccountName: pulpbackup`)
99+
100+
101+
!!! note
102+
Don't forget to rotate the backup files from time to time to avoid filling up the storage.

‎staging_docs/admin/guides/configurations/cache.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Configure Pulp Cache
2+
3+
Pulp can cache the metadata instead of doing "slower" requests into the database (PostgreSQL).
4+
To do so, it uses [Redis as the cache backend](https://pulpproject.org/pulp-operator/docs/admin/guides/configurations/pulp_settings/#cache) technology.
5+
6+
Pulp operator provides a single node Redis server for Pulp to use, but it is also possible to configure the operator to use an external Redis installation.
7+
8+
## Configure Pulp operator to deploy a Redis instance
9+
10+
[Pulp CR page](https://pulpproject.org/pulp-operator/docs/admin/reference/custom_resources/repo_manager/#cache) has all the parameters that can be set to inform Pulp operator how it should deploy the Redis container.
11+
12+
If no `cache` parameter is defined, Pulp operator will deploy Redis with the following configuration:
13+
14+
* a `Deployment` will be provisioned to handle Redis pod
15+
* a single Redis replica will be available (it is **not** possible to form a cluster with this container)
16+
* it will deploy a `docker.io/library/redis:latest` image
17+
18+
A `Service` will be created with the Redis pod as endpoint.
19+
20+
Here is an example of how to configure Pulp operator to deploy the Redis cache:
21+
```
22+
...
23+
spec:
24+
cache:
25+
enabled: true
26+
...
27+
```
28+
29+
## Configure Pulp operator to use an external Redis installation
30+
31+
It is also possible to configure Pulp operator to point to a running Redis cluster.
32+
To do so, create a new `Secret` with the parameters to connect to the running Redis cluster:
33+
```
34+
$ kubectl -npulp create secret generic external-redis \
35+
--from-literal=REDIS_HOST=my-redis-host.example.com \
36+
--from-literal=REDIS_PORT=6379 \
37+
--from-literal=REDIS_PASSWORD="" \
38+
--from-literal=REDIS_DB=""
39+
```
40+
41+
Make sure to define all the keys (`REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`) even if Redis cluster has
42+
no authentication, like in the above example.
43+
44+
Now, configure Pulp operator CR to use the Secret:
45+
```
46+
...
47+
spec:
48+
cache:
49+
enabled: true
50+
external_cache_secret: external-redis
51+
...
52+
```

‎staging_docs/admin/guides/configurations/content_checksums.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Configure Pulp Allowed Content Checksums
2+
3+
During repositories synchronization, Pulp checks the downloaded files against a list
4+
of checksums algorithms. Together with a valid (and trusted) release file signature this will guarantee the integrity of the synchronized repository.
5+
6+
The list of checksums algorithms is defined using the `ALLOWED_CONTENT_CHECKSUMS` setting.
7+
For more information on how `Pulp` uses the checksums check: [https://pulpproject.org/pulp_deb/docs/user/guides/checksums/#configuring-checksums](https://pulpproject.org/pulp_deb/docs/user/guides/checksums/#configuring-checksums)
8+
9+
10+
To set the `ALLOWED_CONTENT_CHECKSUMS` in Pulp Operator, update Pulp CR with:
11+
```yaml
12+
spec:
13+
allowed_content_checksums:
14+
- sha256
15+
```
16+
17+
!!! note
18+
`sha256` is a mandatory checksum.
19+
The possible checksums are: `md5`, `sha1`,`sha256`,`sha512`.
20+
21+
After modifying the `allowed_content_checksums` field in Pulp CR, the operator will create a kubernetes job to run the `pulpcore-manager handle-artifact-checksums` command to ensure database consistency.
22+
23+
!!! note
24+
Missing checksums will need to be recalculated for all your artifacts which can take some time.

‎staging_docs/admin/guides/configurations/customCA.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Certificate injection in Pulp containers
2+
3+
In OpenShift environments, it is possible to [mount additional trust bundles](https://docs.openshift.com/container-platform/4.10/networking/configuring-a-custom-pki.html#certificate-injection-using-operators_configuring-a-custom-pki) into Pulp containers.
4+
5+
Pulp operator handles part of the process.
6+
7+
When `trusted_ca: true` Pulp operator will automatically create and mount a `ConfigMap` with the custom CA into Pulp pods, but before doing so users need to first follow the steps from [Enabling the cluster-wide proxy](https://docs.openshift.com/container-platform/4.10/networking/configuring-a-custom-pki.html#nw-proxy-configure-object_configuring-a-custom-pki) to "register" the custom CA certificate into the cluster.
8+
9+
10+
!!! info
11+
12+
It is recommended to execute the previous steps in a maintenance window because, since this is cluster-wide modification, the cluster can get unavailable if executed wrong (some cluster operators pods will be restarted).

0 commit comments

Comments
 (0)