Skip to content

Commit 9dbe3a4

Browse files
rjeberhardrjeberhard
committed
Merge branch 'cleanup-persistent-storage-and-README' into 'main'
Cleaned up persistent storage section, renamed the PV helper lifecycle script and updated README files See merge request weblogic-cloud/weblogic-kubernetes-operator!4328
2 parents c3819c1 + 9e7ae6c commit 9dbe3a4

File tree

14 files changed

+160
-156
lines changed

14 files changed

+160
-156
lines changed

‎documentation/site/content/managing-domains/domain-on-pv/usage.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -405,7 +405,7 @@ in the directory specified in `domain.spec.domainHome`, and the application dire
405405
406406
1. If the underlying storage volume is dynamically allocated, then delete the PVC with `ReclaimPolcy: delete` and recreate the PVC.
407407
2. Attach a pod to the shared volume and then access the pod to remove the contents. See the sample script,
408-
[Domain on PV helper script](https://github.com/oracle/weblogic-kubernetes-operator/blob/main/kubernetes/samples/scripts/domain-lifecycle/domain-on-pv-helper.sh).
408+
[PV and PVC helper script](https://github.com/oracle/weblogic-kubernetes-operator/blob/main/kubernetes/samples/scripts/domain-lifecycle/pv-pvc-helper.sh).
409409
3. Delete the domain resource.
410410
411411
```

‎documentation/site/content/managing-domains/persistent-storage/_index.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
+++
2-
title = "Persistent volumes"
2+
title = "Persistent storage"
33
date = 2019-02-23T16:45:09-05:00
44
weight = 7.5
55
pre = "<b> </b>"
66
description = "Use a Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC) to store WebLogic domain homes and log files."
77
+++
88

9+
This section provides general information about setting up persistent storage, which can be used for WebLogic domain homes and log files.
10+
911
{{% children style="h4" description="true" %}}

‎documentation/site/content/managing-domains/persistent-storage/oci-fss-pv.md

Lines changed: 51 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -11,90 +11,69 @@ an update to properly initialize the file ownership on the persistent volume
1111
when the domain is initially created."
1212
---
1313

14-
If you are running your Kubernetes cluster on Oracle Container Engine
15-
for Kubernetes (commonly known as OKE), and you use Oracle Cloud Infrastructure File Storage (FSS)
16-
for persistent volumes to store the WebLogic domain home, then the file system
17-
handling, as demonstrated in the operator persistent volume sample, will require
18-
an update to properly initialize the file ownership on the persistent volume
19-
when the domain is initially created.
14+
Oracle recommends using Oracle Cloud Infrastructure File Storage (FSS) for persistent volumes to store
15+
the WebLogic domain home or log files when running the Kubernetes cluster on Oracle Container Engine
16+
for Kubernetes (OKE). When using the FSS with OKE for domain home or log files, the file system
17+
handling will require an update to properly initialize the file ownership on the persistent volume
18+
when the domain is initially created.
2019

2120
{{% notice note %}}
2221
File permission handling on persistent volumes can differ between
2322
cloud providers and even with the underlying storage handling on
24-
Linux based systems. These instructions provide one option to
25-
update file ownership used by the standard Oracle images where
26-
UID `1000` and GID `1000` typically represent the `oracle` or `opc` user.
27-
For more information on persistent volume handling,
28-
see [Persistent storage]({{< relref "/managing-domains/persistent-storage/_index.md" >}}).
23+
Linux-based systems.
24+
The operator requires permission to create directories on the persistent volume under the shared mount path.
25+
The following instructions provide an option to update the file ownership and permissions.
2926
{{% /notice %}}
3027

3128

32-
#### Failure during domain creation with persistent volume sample
29+
#### Updating the permissions of shared directory on persistent storage
30+
The operator provides a utility script, `pv-pvc-helper.sh`, as part of the lifecycle scripts to change the ownership and permissions of the shared directory on the persistent storage.
3331

34-
The existing sample for [creation of a domain home on persistent volume](https://github.com/oracle/weblogic-kubernetes-operator/tree/{{< latestMinorVersion >}}/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv)
35-
uses a Kubernetes Job to create the domain. The sample uses an
36-
`initContainers` section to change the file ownership which will
37-
fail for Oracle Cloud Infrastructure FSS created volumes used with an OKE cluster.
32+
This script launches a Pod and mounts the specified PVC in the Pod containers at the specified mount path. You can then `exec` in the Pod and manually change the permissions or ownership.
33+
34+
See the `pv-pvc-helper.sh` in "Examine, change permissions or delete PV contents" section in the [README](https://github.com/oracle/weblogic-kubernetes-operator/tree/{{< latestMinorVersion >}}/kubernetes/samples/scripts/domain-lifecycle/README.md) file for the script details.
35+
36+
For example, run the following command to create the Pod.
3837

39-
The Oracle Cloud Infrastructure FSS volume contains some files that are not modifiable thus
40-
causing the Kubernetes Job to fail. The failure is seen in the
41-
description of the Kubernetes Job pod:
42-
```shell
43-
$ kubectl describe -n domain1-ns pod domain1-create-weblogic-sample-domain-job-wdkvs
44-
```
4538
```
46-
Init Containers:
47-
fix-pvc-owner:
48-
Container ID: docker://7051b6abdc296c76e937246df03d157926f2f7477e63b6af3bf65f6ae1ceddee
49-
Image: container-registry.oracle.com/middleware/weblogic:12.2.1.3
50-
Image ID: docker-pullable://container-registry.oracle.com/middleware/weblogic@sha256:47dfd4fdf6b56210a6c49021b57dc2a6f2b0d3b3cfcd253af7a75ff6e7421498
51-
Port: <none>
52-
Host Port: <none>
53-
Command:
54-
sh
55-
-c
56-
chown -R 1000:0 /shared
57-
State: Terminated
58-
Reason: Error
59-
Exit Code: 1
60-
Started: Wed, 12 Feb 2020 18:28:53 +0000
61-
Finished: Wed, 12 Feb 2020 18:28:53 +0000
62-
Ready: False
63-
Restart Count: 0
64-
Environment: <none>
39+
$ pv-pvc-helper.sh -n sample-domain1-ns -r -c sample-domain1-weblogic-sample-pvc -m /shared
6540
```
66-
**NOTE**: As of December, 2022, Oracle will continue support of WebLogic Server 12.2.1.3, for six months _only_, for PSUs and security patches. CPU images for WebLogic Server 12.2.1.3 will be published in the January, 2023, and April, 2023, CPU cycles.
6741

68-
#### Updating the domain on persistent volume sample
69-
In the following snippet of the [create-domain-job-template.yaml](https://github.com/oracle/weblogic-kubernetes-operator/blob/{{< latestMinorVersion >}}/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/create-domain-job-template.yaml),
70-
you can see the updated `command` for the init container:
71-
```yaml
72-
apiVersion: batch/v1
73-
kind: Job
42+
The script will create a Pod with the following specifications.
43+
```
44+
apiVersion: v1
45+
kind: Pod
7446
metadata:
75-
name: %DOMAIN_UID%-create-weblogic-sample-domain-job
76-
namespace: %NAMESPACE%
47+
name: pvhelper
48+
namespace: sample-domain1-ns
7749
spec:
78-
template:
79-
metadata:
80-
...
81-
spec:
82-
restartPolicy: Never
83-
initContainers:
84-
- name: fix-pvc-owner
85-
image: %WEBLOGIC_IMAGE%
86-
command: ["sh", "-c", "chown 1000:0 %DOMAIN_ROOT_DIR%/. && find %DOMAIN_ROOT_DIR%/. -maxdepth 1 ! -name '.snapshot' ! -name '.' -print0 | xargs -r -0 chown -R 1000:0"]
87-
volumeMounts:
88-
- name: weblogic-sample-domain-storage-volume
89-
mountPath: %DOMAIN_ROOT_DIR%
90-
securityContext:
91-
runAsUser: 0
92-
runAsGroup: 0
93-
containers:
94-
- name: create-weblogic-sample-domain-job
95-
image: %WEBLOGIC_IMAGE%
96-
...
50+
containers:
51+
- args:
52+
- sleep
53+
- infinity
54+
image: ghcr.io/oracle/oraclelinux:8-slim
55+
name: pvhelper
56+
volumeMounts:
57+
- name: pv-volume
58+
mountPath: /shared
59+
volumes:
60+
- name: pv-volume
61+
persistentVolumeClaim:
62+
claimName: wko-domain-on-pv-pvc
63+
```
64+
65+
Run the following command to `exec` into the Pod.
66+
```
67+
$ kubectl -n sample-domain1-ns exec -it pvhelper -- /bin/sh
68+
```
69+
70+
After you get a shell to the running Pod container, change the directory to `/shared`, and you can change the ownership or permissions using the appropriate `chown` or `chmod` commands. For example,
71+
72+
```
73+
$ chown 1000:0 /shared/. && find /shared/. -maxdepth 1 ! -name '.snapshot' ! -name '.' -print0 | xargs -r -0 chown -R 1000:0
9774
```
98-
Use this new `command` in your copy of this template file. This will result in
99-
the ownership being updated for the expected files only, before the WebLogic
100-
domain is created on the persistent volume.
75+
76+
#### References
77+
78+
- [Provisioning PVCs on the File Storage Service (FSS)](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengcreatingpersistentvolumeclaim_Provisioning_PVCs_on_FSS.htm#Provisioning_Persistent_Volume_Claims_on_the_FileStorageService) in the OCI documentation.
79+
- [Setting up storage for Kubernetes clusters](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengcreatingpersistentvolumeclaim.htm) in the OCI documentation.

‎documentation/site/content/managing-domains/persistent-storage/host-paths.md renamed to ‎documentation/site/content/managing-domains/persistent-storage/pv-pvc.md

Lines changed: 9 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
+++
2-
title = "Host paths and other PVs"
2+
title = "PersistentVolumes and PersistentVolumeClaims"
33
date = 2019-02-23T16:45:09-05:00
44
weight = 1
55
description = "Use a Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC) to store WebLogic domain homes and log files."
@@ -15,52 +15,18 @@ The following prerequisites must be fulfilled before proceeding with the creatio
1515
* Make sure that all the servers in the WebLogic domain are able to reach the storage location.
1616
* Make sure that the host directory that will be used, already exists and has the appropriate file permissions set.
1717

18-
### Storage locations
18+
### Persistent volume storage locations
1919
PersistentVolumes can point to different storage locations, for example NFS servers or a local directory path. For a list of available options, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/).
2020

21-
**Note regarding HostPath**: In a single-node Kubernetes cluster, such as may be used for testing or proof of concept activities, `HOST_PATH` provides the simplest configuration. In a multinode Kubernetes cluster, a `HOST_PATH` that is located on shared storage mounted by all nodes in the Kubernetes cluster is the simplest configuration. If nodes do not have shared storage, then NFS is probably the most widely available option. There are other options listed in the referenced table.
21+
**Note regarding HostPath**: In a single-node Kubernetes cluster, such as may be used for testing or proof of concept activities, `HOST_PATH` provides the simplest configuration. In a multinode Kubernetes cluster, a `HOST_PATH` that is located on shared storage mounted by all nodes in the Kubernetes cluster is the simplest configuration. If nodes do not have shared storage, then NFS is probably the most widely-available option. There are other options listed in the referenced table.
2222

23-
The PersistentVolume for the domain must be created using the appropriate tools before running the script to create the domain. In the simplest case, namely the `HOST_PATH` provider, this means creating a directory on the Kubernetes master and ensuring that it has the correct permissions:
23+
The operator provides a sample script to create the PersistentVolume and PersistentVolumeClaim for the domain. This script must be executed before creating the domain. Beginning with operator version 4.1.0, for the Domain on PV [domain home source type]({{< relref "/managing-domains/choosing-a-model/_index.md" >}}), the operator provides options to create the PV and PVC during the domain initialization. See the [Domain on PV documentation]({{< relref "/managing-domains/domain-on-pv/_index.md" >}}) or the `domain.spec.configuration.initializeDomainOnPV` section in the domain resource [schema](https://github.com/oracle/weblogic-kubernetes-operator/blob/{{< latestMinorVersion >}}/documentation/domains/Domain.md) for more details.
2424

25-
```shell
26-
$ mkdir -m 777 -p /path/to/domain1PersistentVolume
27-
```
28-
29-
**Note regarding NFS**: In the current GA version, the Oracle Container Engine for Kubernetes supports network block storage that can be shared across nodes with access permission RWOnce (meaning that only one can write, others can read only). At this time, the WebLogic on Kubernetes domain created by the WebLogic Kubernetes Operator, requires a shared file system to store the WebLogic domain configuration, which MUST be accessible from all the pods across the nodes. As a workaround, you need to install an NFS server on one node and share the file system across all the nodes.
30-
31-
#### PersistentVolume GID annotation
32-
33-
The `HOST_PATH` directory permissions can be made more secure by using a Kubernetes annotation on the
34-
PersistentVolume that provides the group identifier (GID) which will be added to pods using the PersistentVolume.
35-
36-
For example, if the GID of the directory is `6789`, then the directory can be updated to remove permissions
37-
other than for the user and group along with the PersistentVolume being annotated with the specified GID:
25+
#### Persistent volumes using HostPath approach
26+
The `HOST_PATH` provider is the simplest case for creating a PersistentVolume. It requires creating a directory on the Kubernetes master and ensuring that it has the correct permissions:
3827

3928
```shell
40-
$ chmod 770 /path/to/domain1PersistentVolume
41-
```
42-
```shell
43-
$ kubectl annotate pv domain1-weblogic-sample-pv pv.beta.kubernetes.io/gid=6789
44-
```
45-
46-
After the domain is created and servers are running, the group ownership of the PersistentVolume files
47-
can be updated to the specified GID which will provide read access to the group members. Typically,
48-
files created from a pod onto the PersistentVolume will have UID `1000` and GID `1000` which is the
49-
`oracle` user from the WebLogic Server image.
50-
51-
An example of updating the group ownership on the PersistentVolume would be as follows:
52-
53-
```shell
54-
$ cd /path/to/domain1PersistentVolume
55-
```
56-
```shell
57-
$ sudo chgrp 6789 applications domains logs stores
58-
```
59-
```shell
60-
$ sudo chgrp -R 6789 domains/
61-
```
62-
```shell
63-
$ sudo chgrp -R 6789 logs/
29+
$ mkdir -m 777 -p /path/to/domain1PersistentVolume
6430
```
6531

6632
### YAML files
@@ -69,16 +35,7 @@ Persistent volumes and claims are described in YAML files. For each PersistentVo
6935

7036
For sample YAML templates, refer to the [PersistentVolumes example]({{< relref "/samples/storage/_index.md" >}}).
7137

72-
### Kubernetes resources
73-
74-
After you have written your YAML files, use them to create the PersistentVolume by creating Kubernetes resources using the `kubectl create -f` command:
75-
76-
```shell
77-
$ kubectl create -f pv.yaml
78-
```
79-
```shell
80-
$ kubectl create -f pvc.yaml
81-
```
38+
For more details, refer to Kubernetes PV/PVC examples [here](https://github.com/kubernetes/examples/tree/master/staging/volumes).
8239

8340
#### Verify the results
8441

@@ -97,10 +54,6 @@ This section provides details of common problems that might occur while running
9754

9855
#### PersistentVolume provider not configured correctly
9956

100-
Possibly the most common problem experienced during testing was the incorrect configuration of the PersistentVolume provider. The PersistentVolume must be accessible to all Kubernetes Nodes, and must be able to be mounted as Read/Write/Many. If this is not the case, the PersistentVolume creation will fail.
57+
Possibly the most common problem experienced during testing was the incorrect configuration of the PersistentVolume provider. The PersistentVolume must be accessible to all Kubernetes Nodes, and must be able to be mounted as `Read/Write/Many`. If this is not the case, the PersistentVolume creation will fail.
10158

10259
The simplest case is where the `HOST_PATH` provider is used. This can be either with one Kubernetes Node, or with the `HOST_PATH` residing in shared storage available at the same location on every node (for example, on an NFS mount). In this case, the path used for the PersistentVolume must have its permission bits set to 777.
103-
104-
#### Further reading
105-
106-
* See the blog, [How to run WebLogic clusters on the Oracle Cloud Infrastructure Container Engine for Kubernetes](https://blogs.oracle.com/weblogicserver/how-to-run-weblogic-clusters-on-the-oracle-cloud-infrastructure-container-engine-for-kubernetes).

‎documentation/site/content/samples/domains/domain-home-on-pv/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Location | Description |
3636
`kubernetes/samples/scripts/create-weblogic-domain/ingresses` | Ingress resources. |
3737
`kubernetes/samples/scripts/domain-lifecycle/opss-wallet.sh` | Utility script for exporting or importing a JRF domain OPSS wallet file. |
3838
`kubernetes/samples/scripts/domain-lifecycle/waitForDomain.sh` | Utility script that optionally waits for the pods in a domain to reach their expected `Completed`, `image`, and `ready` state. |
39-
`kubernetes/samples/scripts/domain-lifecycle/domain-on-pv-helper.sh` | Utility script to examine or clean up the contents of shared directories on the persistent volume. |
39+
`kubernetes/samples/scripts/domain-lifecycle/pv-pvc-helper.sh` | Utility script to examine or clean up the contents of shared directories on the persistent volume. |
4040

4141
#### Ensuring your Kubernetes cluster can access images
4242

‎documentation/site/content/samples/domains/domain-home-on-pv/prerequisites.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ for the Domain on PV sample.
159159
160160
**NOTE**: The requirements in this section are in addition to [Prerequisites for WLS and JRF domain types](#prerequisites-for-wls-and-jrf-domain-types).
161161
162-
A JRF domain requires an infrastructure database, and configuring your domain to access this database. For more details, see [JRF domain]({{< relref "/managing-domains/domain-on-pv/jrf-domain.md" >}}) in the user documentation. You must perform all these steps _before_ you create your domain.
162+
A JRF domain requires an infrastructure database, and configuring your domain to access this database. For more details, see [JRF domains]({{< relref "/managing-domains/domain-on-pv/jrf-domain.md" >}}) in the user documentation. You must perform all these steps _before_ you create your domain.
163163
164164
##### Set up and initialize an infrastructure database
165165
@@ -222,7 +222,7 @@ When you follow the instructions in the samples, avoid instructions that are `WL
222222
223223
For example, in this sample:
224224
225-
- [JRF Domain YAML](https://raw.githubusercontent.com/oracle/weblogic-kubernetes-operator/{{< latestMinorVersion >}}/kubernetes/samples/scripts/create-weblogic-domain/domain-home-on-pv/domain-resources/JRF/domain-on-pv-JRF-v1.yaml) file has an `configuration.opss.walletPasswordSecret` field that references a secret named `sample-domain1-opss-wallet-password-secret`, with a `walletPassword` of your choice.
225+
- [JRF Domain YAML](https://raw.githubusercontent.com/oracle/weblogic-kubernetes-operator/{{< latestMinorVersion >}}/kubernetes/samples/scripts/create-weblogic-domain/domain-on-pv/domain-resources/JRF/domain-on-pv-JRF-v1.yaml) file has an `configuration.opss.walletPasswordSecret` field that references a secret named `sample-domain1-opss-wallet-password-secret`, with a `walletPassword` of your choice.
226226
227227
- JRF domain creation image models have the following `domainInfo -> RCUDbInfo` stanza that references a `sample-domain1-rcu-access` secret with the appropriate values for attributes, `rcu_prefix`, `rcu_schema_password`, and `rcu_db_conn_string`, for accessing the Oracle database that you deployed to the default namespace as one of the prerequisite steps.
228228

0 commit comments

Comments
 (0)