Document the ability to override the introspector job pod resource settings and name restriction on the converted 3.x aux image init-containers. (#3939)

* Documentation update for the changes to independently configure introspector pod resources and aux image upgrade restriction.

* Changes to allow 'wls-shared-' prefix in the names of the init containers generated during '3.x/v8' aux image config conversion.

* Fix for the environment variables in generated init containers starting with 'compat-' or 'wls-shared'.

Author: ankedia

common/src/main/java/oracle/kubernetes/common/CommonConstants.java

@@ -10,6 +10,7 @@ private CommonConstants() {
   }
 
   public static final String COMPATIBILITY_MODE = "compat-";
+  public static final String WLS_SHARED = "wls-shared-";
   public static final String API_VERSION_V9 = "weblogic.oracle/v9";
   public static final String API_VERSION_V8 = "weblogic.oracle/v8";
 

documentation/4.0/content/faq/resource-settings.md

@@ -40,10 +40,12 @@ You can tune container memory and CPU usage
 by configuring Kubernetes resource requests and limits,
 and you can tune a WebLogic JVM heap usage
 using the `USER_MEM_ARGS` environment variable in your Domain YAML file.
-The introspector job pod uses the same CPU and memory settings as the
+By default, the introspector job pod uses the same CPU and memory settings as the
 domain's WebLogic Administration Server pod. Similarly, the operator created init containers in the
 introspector job pod for the [Auxiliary Images]({{< relref "/managing-domains/model-in-image/auxiliary-images" >}})
 based domains use the same CPU and memory settings as the domain's WebLogic Administration Server pod.
+Beginning with operator version 4.0.5, you can override the settings of the introspector job pod using
+the `domain.spec.introspector.serverPod` element.
 A resource request sets the minimum amount of a resource that a container requires.
 A resource limit is the maximum amount of a resource a container is given
 and prevents a container from using more than its share of a resource.
@@ -61,6 +63,8 @@ and you can override the setting for individual WebLogic Server instances using
 setting for member servers of a cluster using the `cluster.spec.serverPod` element.
 Note that the introspector job pod uses the same settings
 as the WebLogic Administration Server pod.
+Beginning with operator version 4.0.5, you can override the settings of the introspector job pod
+using the `domain.spec.introspector.serverPod` element.
 
 Values set in the `.serverPod` stanzas for a more specific type of pod, override
 the same values if they are also set for a more general type of pod, and inherit

documentation/4.0/content/managing-domains/model-in-image/auxiliary-images.md

@@ -284,13 +284,13 @@ to use Docker to build its auxiliary image:
 ### Automated upgrade of the `weblogic.oracle/v8` schema auxiliary images configuration
 
 {{% notice note %}}
-The automated upgrade described in this section converts `weblogic.oracle/v8` schema auxiliary image configuration into low-level Kubernetes schema, for example, init-containers and volumes.
+The automated upgrade described in this section converts `weblogic.oracle/v8` schema auxiliary image configuration into low-level Kubernetes schema, for example, init containers and volumes.
 Instead of relying on the generated low-level schema, Oracle recommends using a simplified `weblogic.oracle/v9` schema configuration for auxiliary images, as documented in the [Configuration](#configuration) section.
 {{% /notice %}}
 
 In operator version 4.0, we have enhanced auxiliary images to improve ease of use; also, its configuration has changed from operator 3.x releases.
 
-Operator 4.0 provides a seamless upgrade of Domains with `weblogic.oracle/v8` schema auxiliary images configuration. When you create a Domain with auxiliary images using `weblogic.oracle/v8` schema in a namespace managed by the 4.0 operator, the [WebLogic Domain resource conversion webhook]({{< relref "/managing-operators/conversion-webhook.md" >}}) performs an automated upgrade of the domain resource to the `weblogic.oracle/v9` schema. The conversion webhook runtime converts the `weblogic.oracle/v8` auxiliary image configuration to the equivalent configuration using init-containers, volume and volume mounts under the `serverPod` spec in `weblogic.oracle/v9`. Similarly, when [upgrading the operator]({{< relref "/managing-operators/installation#upgrade-the-operator" >}}), Domains with `weblogic.oracle/v8` schema auxiliary images are seamlessly upgraded.
+Operator 4.0 provides a seamless upgrade of Domains with `weblogic.oracle/v8` schema auxiliary images configuration. When you create a Domain with auxiliary images using `weblogic.oracle/v8` schema in a namespace managed by the 4.0 operator, the [WebLogic Domain resource conversion webhook]({{< relref "/managing-operators/conversion-webhook.md" >}}) performs an automated upgrade of the domain resource to the `weblogic.oracle/v9` schema. The conversion webhook runtime converts the `weblogic.oracle/v8` auxiliary image configuration to the equivalent configuration using init containers, volume and volume mounts under the `serverPod` spec in `weblogic.oracle/v9`. Similarly, when [upgrading the operator]({{< relref "/managing-operators/installation#upgrade-the-operator" >}}), Domains with `weblogic.oracle/v8` schema auxiliary images are seamlessly upgraded.
 
 The following is a sample `weblogic.oracle/v8` schema auxiliary image configuration in operator 3.x and
 the equivalent `weblogic.oracle/v9` schema configuration generated by the conversion webhook in operator 4.0.
@@ -344,6 +344,10 @@ spec:
       name: compat-ai-vol-auxiliaryimagevolume1
 ```
 
+{{% notice note %}}
+The conversion webhook runtime creates init containers with names prefixed with `compat-` when converting the auxiliary image configuration of the `weblogic.oracle/v8` schema. The operator generates only init containers with names starting with either `compat-` or `wls-shared-` in the introspector job pod. To alter the generated init container's name, the new name must start with either `compat-` or `wls-shared-`.
+{{% /notice %}}
+
 ### Domain upgrade tool to manually upgrade the `weblogic.oracle/v8` schema domain resource
 
 To manually upgrade the domain resource from the `weblogic.oracle/v8` schema to the `weblogic.oracle/v9` schema, see [Upgrade the `weblogic.oracle/v8` schema domain resource manually]({{< relref "/managing-domains/upgrade-domain-resource#upgrade-the-weblogicoraclev8-schema-domain-resource-manually" >}}).

documentation/4.0/content/managing-domains/upgrade-domain-resource/_index.md

@@ -14,7 +14,7 @@ The Domain CustomResourceDefinition in operator version 4.0 has changed signific
 ### Automated upgrade of `weblogic.oracle/v8` schema domain resource
 
 {{% notice note %}}
-The automated upgrade described in this section converts `weblogic.oracle/v8` schema auxiliary image configuration into low-level Kubernetes schema, for example, init-containers and volumes.
+The automated upgrade described in this section converts `weblogic.oracle/v8` schema auxiliary image configuration into low-level Kubernetes schema, for example, init containers and volumes.
 Instead of relying on the generated low-level schema, Oracle recommends using a simplified `weblogic.oracle/v9` schema configuration for auxiliary images, as documented in the
 Auxiliary Images [Configuration]({{<relref "/managing-domains/model-in-image/auxiliary-images#configuration" >}}) section.
 {{% /notice %}}
@@ -24,7 +24,7 @@ The 4.0 operator provides a seamless upgrade of the Domain resources with the `w
 ### Upgrade the `weblogic.oracle/v8` schema domain resource manually
 
 {{% notice note %}}
-The manual upgrade tooling described in this section converts `weblogic.oracle/v8` schema auxiliary image configuration into low-level Kubernetes schema, for example, init-containers and volumes.
+The manual upgrade tooling described in this section converts `weblogic.oracle/v8` schema auxiliary image configuration into low-level Kubernetes schema, for example, init containers and volumes.
 Instead of relying on the generated low-level schema, Oracle recommends using a simplified `weblogic.oracle/v9` schema configuration for auxiliary images, as documented in the
 Auxiliary Images [Configuration]({{<relref "/managing-domains/model-in-image/auxiliary-images#configuration" >}}) section.
 {{% /notice %}}
@@ -69,3 +69,7 @@ In the previous example, the tool writes the upgraded file to the `/tmp` directo
 $ ls -ltr /tmp/domain-v9.yaml
 -rw-r----- 1 user dba 2818 Apr 18 23:11 /tmp/domain-v9.yaml
 ```
+
+{{% notice note %}}
+The manual upgrade tooling creates init containers with names prefixed with `compat-` when converting the auxiliary image configuration of the `weblogic.oracle/v8` schema. The operator generates only init containers with names starting with either `compat-` or `wls-shared-` in the introspector job pod. To alter the generated init container's name, the new name must start with either `compat-` or `wls-shared-`.
+{{% /notice %}}

operator/src/main/java/oracle/kubernetes/operator/helpers/BasePodStepContext.java

@@ -39,6 +39,7 @@
 import static oracle.kubernetes.common.CommonConstants.COMPATIBILITY_MODE;
 import static oracle.kubernetes.common.CommonConstants.SCRIPTS_MOUNTS_PATH;
 import static oracle.kubernetes.common.CommonConstants.SCRIPTS_VOLUME;
+import static oracle.kubernetes.common.CommonConstants.WLS_SHARED;
 import static oracle.kubernetes.common.helpers.AuxiliaryImageEnvVars.AUXILIARY_IMAGE_PATHS;
 import static oracle.kubernetes.weblogic.domain.model.AuxiliaryImage.AUXILIARY_IMAGE_INTERNAL_VOLUME_NAME;
 
@@ -171,7 +172,7 @@ protected List<V1EnvVar> createEnv(AuxiliaryImage auxiliaryImage, String name) {
   protected List<V1EnvVar> createEnv(V1Container c) {
     List<V1EnvVar> initContainerEnvVars = new ArrayList<>();
     Optional.ofNullable(c.getEnv()).ifPresent(initContainerEnvVars::addAll);
-    if (!c.getName().startsWith(COMPATIBILITY_MODE)) {
+    if (!(c.getName().startsWith(COMPATIBILITY_MODE) || c.getName().startsWith(WLS_SHARED))) {
       getEnvironmentVariables()
           .forEach(envVar -> addIfMissing(initContainerEnvVars,
               envVar.getName(), envVar.getValue(), envVar.getValueFrom()));

operator/src/main/java/oracle/kubernetes/operator/helpers/JobStepContext.java

@@ -57,6 +57,7 @@
 import static oracle.kubernetes.common.CommonConstants.COMPATIBILITY_MODE;
 import static oracle.kubernetes.common.CommonConstants.SCRIPTS_MOUNTS_PATH;
 import static oracle.kubernetes.common.CommonConstants.SCRIPTS_VOLUME;
+import static oracle.kubernetes.common.CommonConstants.WLS_SHARED;
 import static oracle.kubernetes.common.utils.CommonUtils.MAX_ALLOWED_VOLUME_NAME_LENGTH;
 import static oracle.kubernetes.common.utils.CommonUtils.VOLUME_NAME_SUFFIX;
 import static oracle.kubernetes.operator.DomainStatusUpdater.createKubernetesFailureSteps;
@@ -213,19 +214,23 @@ List<V1Volume> getAdditionalVolumes() {
   }
 
   private void addVolumeIfMissing(V1Volume volume, List<V1Volume> volumes) {
-    if (!volumes.contains(volume) && volume.getName().startsWith(COMPATIBILITY_MODE)) {
+    if (!volumes.contains(volume) && isAllowedInIntrospector(volume.getName())) {
       volumes.add(volume);
     }
   }
 
+  private boolean isAllowedInIntrospector(String name) {
+    return name.startsWith(COMPATIBILITY_MODE) || name.startsWith(WLS_SHARED);
+  }
+
   List<V1VolumeMount> getAdditionalVolumeMounts() {
     List<V1VolumeMount> volumeMounts = getDomain().getSpec().getAdditionalVolumeMounts();
     getServerSpec().getAdditionalVolumeMounts().forEach(mount -> addVolumeMountIfMissing(mount, volumeMounts));
     return volumeMounts;
   }
 
   private void addVolumeMountIfMissing(V1VolumeMount mount, List<V1VolumeMount> volumeMounts) {
-    if (!volumeMounts.contains(mount) && mount.getName().startsWith(COMPATIBILITY_MODE)) {
+    if (!volumeMounts.contains(mount) && isAllowedInIntrospector(mount.getName())) {
       volumeMounts.add(mount);
     }
   }
@@ -402,7 +407,7 @@ protected void addInitContainers(V1PodSpec podSpec) {
     List<V1Container> initContainers = new ArrayList<>();
     Optional.ofNullable(getAuxiliaryImages()).ifPresent(auxImages -> addInitContainers(initContainers, auxImages));
     initContainers.addAll(getAdditionalInitContainers().stream()
-            .filter(container -> container.getName().startsWith(COMPATIBILITY_MODE))
+            .filter(container -> isAllowedInIntrospector(container.getName()))
             .map(c -> c.env(createEnv(c)).resources(createResources()))
             .collect(Collectors.toList()));
     podSpec.initContainers(initContainers);

operator/src/main/resources/scripts/auxImage.sh

@@ -48,7 +48,8 @@ if [[ "$AUXILIARY_IMAGE_CONTAINER_NAME" == "operator-aux-container"* ]]; then
   else
     trace FINE "Auxiliary Image: Skipping initialization due to a previous successful initialization."
   fi
-elif [[ "$AUXILIARY_IMAGE_CONTAINER_NAME" == "compat-operator-aux-container"* ]]; then
+elif [[ "$AUXILIARY_IMAGE_CONTAINER_NAME" == "compat-"* ]] \
+     || [[ "$AUXILIARY_IMAGE_CONTAINER_NAME" == "wls-shared-"* ]]; then
   sucFile="${AUXILIARY_IMAGE_TARGET_PATH}/${AUXILIARY_IMAGE_COMMAND_LOGS_DIR}/${AUXILIARY_IMAGE_CONTAINER_NAME}.suc"
   if [ ! -f $sucFile ]; then
     initCompatibilityModeInitContainersWithLegacyAuxImages > /tmp/compatibilityModeInitContainers.out 2>&1

operator/src/test/java/oracle/kubernetes/operator/helpers/JobHelperTest.java

@@ -74,6 +74,7 @@
 
 import static com.meterware.simplestub.Stub.createNiceStub;
 import static oracle.kubernetes.common.CommonConstants.COMPATIBILITY_MODE;
+import static oracle.kubernetes.common.CommonConstants.WLS_SHARED;
 import static oracle.kubernetes.common.logging.MessageKeys.FLUENTD_CONFIGMAP_CREATED;
 import static oracle.kubernetes.common.logging.MessageKeys.FLUENTD_CONFIGMAP_REPLACED;
 import static oracle.kubernetes.common.utils.CommonUtils.getMD5Hash;
@@ -1028,6 +1029,19 @@ void introspectorPodSpec_createdWithConfiguredAuxImageInitContainers() {
     assertThat(getNumPodSpecInitContainers(jobSpec), equalTo(1));
   }
 
+  @Test
+  void introspectorPodSpec_createdWithConfiguredWlsSharedInitContainers() {
+    configureDomain()
+        .withInitContainer(
+            createContainer(
+                WLS_SHARED + "aux-image-container", "busybox", "sh", "-c",
+                "echo managed server && sleep 120"));
+
+    V1JobSpec jobSpec = createJobSpec();
+
+    assertThat(getNumPodSpecInitContainers(jobSpec), equalTo(1));
+  }
+
   @Test
   void introspectorPodSpec_createdWithConfiguredAuxImageInitContainersHavingIntrospectorResources() {
     configureDomain()
@@ -1053,6 +1067,27 @@ private V1ResourceRequirements getInitContainerResources(V1PodSpec podSpec) {
     return podSpec.getInitContainers().stream().findFirst().get().getResources();
   }
 
+  @Test
+  void introspectorPodSpec_createdWithConfiguredWlsSharedInitContainersHavingIntrospectorResources() {
+    configureDomain()
+        .withInitContainer(
+            createContainer(
+                WLS_SHARED + "aux-image-container", "busybox", "sh", "-c",
+                "echo managed server && sleep 120"))
+        .configureIntrospector()
+        .withRequestRequirement("cpu", "512m")
+        .withLimitRequirement("memory", "1Gi");    ;
+
+    V1JobSpec jobSpec = createJobSpec();
+
+    assertThat(getNumPodSpecInitContainers(jobSpec), equalTo(1));
+    V1PodSpec podSpec = getPodSpec(jobSpec);
+    assertThat(
+        getInitContainerResources(podSpec),
+        is(new V1ResourceRequirements().requests(Collections.singletonMap("cpu", new Quantity("512m")))
+            .limits(Collections.singletonMap("memory", new Quantity("1Gi")))));
+  }
+
   @Test
   void introspectorPodSpec_createdWithoutConfiguredContainers() {
     configureDomain()
@@ -1081,6 +1116,19 @@ void whenAdminServerHasLegacyAuxImageInitContainers_introspectorPodStartupWithTh
     assertThat(getNumPodSpecInitContainers(jobSpec), equalTo(1));
   }
 
+  @Test
+  void whenAdminServerHasWlsSharedInitContainers_introspectorPodStartupWithThem() {
+    configureDomain()
+        .configureAdminServer()
+        .withInitContainer(
+            createContainer(
+                WLS_SHARED + "aux-image-container", "busybox", "sh", "-c",
+                "echo managed server && sleep 120"));
+    V1JobSpec jobSpec = createJobSpec();
+
+    assertThat(getNumPodSpecInitContainers(jobSpec), equalTo(1));
+  }
+
   @Test
   void whenAdminServerHasNormalInitContainers_introspectorPodStartupWithoutThem() {
     configureDomain()
@@ -1144,6 +1192,18 @@ void whenAdminServerHasLegacyAuxImageVolumeMount_introspectorPodStartupWithoutTh
           .orElse(Collections.emptyList()).size(), equalTo(4));
   }
 
+  @Test
+  void whenAdminServerHasWlsSharedVolumeMount_introspectorPodStartupWithoutThem() {
+    configureDomain()
+        .configureAdminServer()
+        .withAdditionalVolumeMount(WLS_SHARED + "aux-image-container_volume", "/test");
+
+    V1JobSpec jobSpec = createJobSpec();
+
+    assertThat(getMatchingContainer(domainPresenceInfo, jobSpec).map(V1Container::getVolumeMounts)
+        .orElse(Collections.emptyList()).size(), equalTo(4));
+  }
+
   @Test
   void introspectorPodContainerSpec_hasJobNameAsContainerName() {
     V1JobSpec jobSpec = createJobSpec();