kubectl explain
Use this document to create your own Domain resource, which can be used to configure the operation of your WebLogic Server domain. The Domain resource does not replace the traditional domain configuration files, but instead cooperates with those files to describe the Kubernetes artifacts of the corresponding domain. For instance, the domain configuration will still specify deployed applications, data sources, and most other details about the domain while the Domain resource will specify the number of cluster members currently running or the persistent volumes that will be mounted into the containers running WebLogic Server instances.
Many of the samples accompanying the operator project include scripts to generate an initial Domain resource from a set of simplified inputs; however, the Domain resource is the actual source of truth for how the operator will manage each WebLogic Server domain. You are encouraged to either start with the Domain resource YAML files generated by the various samples or create Domain resources manually or by using other tools based on the schema referenced here or this documentation.
The following prerequisites must be fulfilled before proceeding with the creation of a domain resource:
spec.webLogicCredentialsSecret
field that references a Kubernetes Secret containing the username
and password
of the WebLogic server administrative account.For example, see the Quick Start.
Domains are defined using YAML files. For each WebLogic Server domain you want to run, you should create one Domain resource YAML file and apply it. In the example referenced below, the sample scripts generate a Domain resource YAML file that you can use as a basis. Copy the file and override the default settings so that it matches all the WebLogic Server domain parameters that define your domain.
See the WebLogic Server samples, Domain home on a PV, Domain home in Image, and Model in Image.
After you have written your YAML files, you use them to create your domain artifacts using the kubectl apply -f
command.
$ kubectl apply -f domain-resource.yaml
To confirm that the Domain was created, use this command:
$ kubectl get domains -n [namespace]
To view all of the attributes of a running domain, including the domain’s status, use this command:
$ kubectl describe domain [domain name] -n [namespace]
Or this command:
$ kubectl get domain [domain name] -n [namespace] -o yaml
The domain resource metadata
section names the Domain and its namespace. The name of the Domain is the default value for the domainUID
which is used by the operator to distinguish domains running in the Kubernetes cluster that may have the same domain name. The Domain name must be unique in the namespace and the domainUID
should be unique across the cluster. The domainUID
, Domain resource name, and domain name (from the WebLogic domain configuration) may all be different.
The domain resource spec
section describes the intended running state of the domain, including intended runtime state of WebLogic Server instances, number of cluster members started, and details about Kubernetes Pod or Service generation, such as resource constraints, scheduling requirements, or volume mounts.
The operator automatically updates the status
section of a deploy domain resource to describe the actual running state of the domain, including WebLogic Server instance runtime states and current health.
Here are some references you can use for the fields in these sections:
kubectl explain
If you are using Kubernetes 1.16 or later, you can access the description of any field of the Domain using kubectl explain
. For instance, the following command displays the description of the domainUID
field:
$ kubectl explain domain.spec.domainUID
KIND: Domain
VERSION: weblogic.oracle/v8
FIELD: domainUID <string>
DESCRIPTION:
Domain unique identifier. It is recommended that this value be unique to
assist in future work to identify related domains in active-passive
scenarios across data centers; however, it is only required that this value
be unique within the namespace, similarly to the names of Kubernetes
resources. This value is distinct and need not match the domain name from
the WebLogic domain configuration. Defaults to the value of
`metadata.name`.
The Domain spec
section contains elements for configuring the domain operation and sub-sections specific to the Administration Server, specific clusters, or specific Managed Servers.
NOTE: This section details elements that are unique to the operator. For more general Kubernetes pod elements such as environment variables, node affinity, and volumes, see Domain resource attribute references.
Elements related to domain identification, container image, and domain home:
domainUID
: Domain unique identifier. This identifier is required to be no more than 45 characters, and practically, should be shorter to help ensure Kubernetes restrictions are met (for more details, see Meet Kubernetes resource name restrictions). It is recommended that this value be unique to assist in future work to identify related domains in active-passive scenarios across data centers; however, it is only required that this value be unique within the namespace, similarly to the names of Kubernetes resources. This value is distinct and need not match the domain name from the WebLogic domain configuration. Defaults to the value of metadata.name
.image
: The WebLogic container image; required when domainHomeSourceType
is Image or FromModel; otherwise, defaults to container-registry.oracle.com/middleware/weblogic:12.2.1.4.imagePullPolicy
: The image pull policy for the WebLogic container image. Legal values are Always, Never, and IfNotPresent. Defaults to Always if image ends in :latest; IfNotPresent, otherwise.imagePullSecrets
: A list of image pull Secrets for the WebLogic container image.domainHome
: The directory containing the WebLogic domain configuration inside the container. Defaults to /shared/domains/domains/ if domainHomeSourceType
is PersistentVolume. Defaults to /u01/oracle/user_projects/domains/ if domainHomeSourceType
is Image. Defaults to /u01/domains/ if domainHomeSourceType
is FromModel.domainHomeSourceType
: Domain home file system source type: Legal values: Image, PersistentVolume, FromModel. Image indicates that the domain home file system is present in the container image specified by the image
field. PersistentVolume indicates that the domain home file system is located on a persistent volume. FromModel indicates that the domain home file system will be created and managed by the operator based on a WDT domain model. If this field is specified, it overrides the value of domainHomeInImage
. If both fields are unspecified, then domainHomeSourceType
defaults to Image.dataHome
: An optional directory in a server’s container for data storage of default and custom file stores. If dataHome
is not specified or its value is either not set or empty, then the data storage directories are determined from the WebLogic domain configuration.Elements related to logging:
includeServerOutInPodLog
: Specifies whether the server .out file will be included in the Pod’s log. Defaults to true.logHome
: The directory in a server’s container in which to store the domain, Node Manager, server logs, server *.out, introspector .out, and optionally HTTP access log files if httpAccessLogInLogHome
is true. Ignored if logHomeEnabled
is false.logHomeEnabled
: Specifies whether the log home folder is enabled. Defaults to true if domainHomeSourceType
is PersistentVolume; false, otherwise.httpAccessLogInLogHome
: Specifies whether the server HTTP access log files will be written to the same directory specified in logHome
. Otherwise, server HTTP access log files will be written to the directory configured in the WebLogic domain configuration. Defaults to true.Elements related to security:
webLogicCredentialsSecret
: Reference to a Kubernetes Secret that contains the user name and password needed to boot a WebLogic Server under the username
and password
fields.configuration
below.Elements related to domain startup and shutdown:
serverStartPolicy
: The strategy for deciding whether to start a WebLogic Server instance. Legal values are ADMIN_ONLY, NEVER, or IF_NEEDED. Defaults to IF_NEEDED.serverStartState
: The WebLogic runtime state in which the server is to be started. Use ADMIN if the server should start in the admin state. Defaults to RUNNING.restartVersion
: Changes to this field cause the operator to restart WebLogic Server instances.replicas
: The default number of cluster member Managed Server instances to start for each WebLogic cluster in the domain configuration, unless replicas
is specified for that cluster under the clusters
field. For each cluster, the operator will sort cluster member Managed Server names from the WebLogic domain configuration by normalizing any numbers in the Managed Server name and then sorting alphabetically. This is done so that server names such as “managed-server10” come after “managed-server9”. The operator will then start Managed Servers from the sorted list, up to the replicas
count, unless specific Managed Servers are specified as starting in their entry under the managedServers
field. In that case, the specified Managed Servers will be started and then additional cluster members will be started, up to the replicas
count, by finding further cluster members in the sorted list that are not already started. If cluster members are started because of their entries under managedServers
, then a cluster may have more cluster members running than its replicas
count. Defaults to 0.maxClusterConcurrentStartup
: The maximum number of cluster member Managed Server instances that the operator will start in parallel for a given cluster, if maxConcurrentStartup
is not specified for a specific cluster under the clusters
field. A value of 0 means there is no configured limit. Defaults to 0.allowReplicasBelowMinDynClusterSize
: Whether to allow the number of running cluster member Managed Server instances to drop below the minimum dynamic cluster size configured in the WebLogic domain configuration, if this is not specified for a specific cluster under the clusters
field. Defaults to true.introspectVersion
: Changes to this field cause the operator to repeat its introspection of the WebLogic domain configuration (see Initiating introspection). Repeating introspection is required for the operator to recognize changes to the domain configuration, such as adding a new WebLogic cluster or Managed Server instance, to regenerate configuration overrides, or to regenerate the WebLogic domain home when the domainHomeSourceType
is FromModel. Introspection occurs automatically, without requiring change to this field, when servers are first started or restarted after a full domain shut down. For the FromModel domainHomeSourceType
, introspection also occurs when a running server must be restarted because of changes to any of the fields listed here. See also overrideDistributionStrategy
.Elements related to specifying and overriding WebLogic domain configuration:
These elements are under configuration
.
overridesConfigMap
: The name of the ConfigMap for WebLogic configuration overrides. If this field is specified, then the value of spec.configOverrides
is ignored.overrideDistributionStrategy
: Determines how updated configuration overrides are distributed to already running WebLogic Server instances following introspection when the domainHomeSourceType
is PersistentVolume or Image. Configuration overrides are generated during introspection from Secrets, the overridesConfigMap
field, and WebLogic domain topology. Legal values are DYNAMIC, which means that the operator will distribute updated configuration overrides dynamically to running servers, and ON_RESTART, which means that servers will use updated configuration overrides only after the server’s next restart. The selection of ON_RESTART will not cause servers to restart when there are updated configuration overrides available. See also introspectVersion
. Defaults to DYNAMIC.secrets
: A list of names of the Secrets for WebLogic configuration overrides or model. If this field is specified, then the value of spec.configOverrideSecrets
is ignored.introspectorJobActiveDeadlineSeconds
: The introspector job timeout value in seconds. If this field is specified, then the operator’s ConfigMap data.introspectorJobActiveDeadlineSeconds
value is ignored. Defaults to 120 seconds.These elements are under configuration.model
, only apply if the domainHomeSourceType
is FromModel
, and are discussed in Model in Image.
configMap
: (Optional) Name of a ConfigMap containing WebLogic Deploy Tooling model YAML files or .properties
files.domainType
: WebLogic Deploy Tooling domain type. Legal values: WLS, RestrictedJRF, JRF. Defaults to WLS.runtimeEncryptionSecret
: The name of the Secret containing the runtime encryption password, which must be in a field named password
. Required when domainHomeSourceType
is set to FromModel
.modelHome
: Location of the WebLogic Deploy Tooling model home directory, which can include model YAML files, .properties
variable files, and application .zip
archives. Defaults to /u01/wdt/models
.onlineUpdate.*
: Settings related to the online update option for Model In Image dynamic updates.
onlineUpdate.enabled
: Enable online update for model changes to a running domain. Default is false
.onlineUpdate.onNonDynamicChanges
:
Controls behavior when non-dynamic WebLogic configuration changes are
detected during an online update.
Non-dynamic changes are changes that require a domain restart to take effect.
Valid values are CommitUpdateOnly
(default) and CommitUpdateAndRoll
.
For more information, see
Online update handling of non-dynamic WebLogic configuration changes
in the Runtime Updates section of the Model in Image user guide.onlineUpdate.wdtTimeouts.*
: Rarely needed timeout settings for online update calls to the
WebLogic domain from the WebLogic Deploy Tool within the introspector job. All timeouts
are specified in milliseconds and default to two or three minutes. For a full list of
timeouts, call kubectl explain domain.spec.configuration.model.onlineUpdate.wdtTimeouts
.These elements are under configuration.opss
, and only apply if the domainHomeSourceType
is FromModel
and the domainType
is JRF
.
walletPasswordSecret
: Name of a Secret containing the OPSS key passphrase, which must be in a field named walletPassword
. Used to encrypt and decrypt the wallet that is used for accessing the domain’s entries in its RCU database.walletFileSecret
: Name of a Secret containing the OPSS key wallet file, which must be in a field named walletFile
. Use this to allow a JRF domain to reuse its entries in the RCU database. This allows you to specify a wallet file that was obtained from the domain home after the domain was booted for the first time.These elements are under configuration.istio
.
enabled
: True, if this domain is deployed under an Istio service mesh.
Defaults to true when the istio
field is specified.readinessPort
:
The operator will create WebLogic network access points
with this port on each WebLogic Server.
The readiness probe on each pod will use these
network access points
to verify that the pod is ready
for application traffic. Defaults to 8888.replicationChannelPort
:
The operator will create a T3
protocol
WebLogic network access point
on each WebLogic Server that is part of a cluster with this port
to handle EJB and servlet session state replication traffic
between servers. This setting is ignored for clusters
where the WebLogic cluster configuration already
defines a replication-channel
attribute. Defaults to 4564.localhostBindingsEnabled
:
This setting was added in operator version 3.3.3,
defaults to true
.
When true
, the operator
creates a WebLogic
network access point with a localhost
binding for each existing channel and protocol.
Use true
for Istio versions prior to 1.10
and set to false
for version 1.10 and later.Elements related to Kubernetes Pod and Service generation:
serverPod
: Customization affecting the generation of Pods for WebLogic Server instances.serverService
: Customization affecting the generation of ClusterIP Services for WebLogic Server instances.Sub-sections related to the Administration Server, specific clusters, or specific Managed Servers:
adminServer
: Lifecycle options for the Administration Server, including Java options, environment variables, additional Pod content, and which channels or network access points should be exposed using a NodePort Service.clusters
: Lifecycle options for all of the Managed Server members of a WebLogic cluster, including Java options, environment variables, additional Pod content, and the ability to explicitly start, stop, or restart cluster members. The clusterName
field of each entry must match a cluster that already exists in the WebLogic domain configuration.managedServers
: Lifecycle options for individual Managed Servers, including Java options, environment variables, additional Pod content, and the ability to explicitly start, stop, or restart a named server instance. The serverName
field of each entry must match a Managed Server that already exists in the WebLogic domain configuration or that matches a dynamic cluster member based on the server template.The elements serverStartPolicy
, serverStartState
, serverPod
and serverService
are repeated under adminServer
and under each entry of clusters
or managedServers
. The values directly under spec
, set the defaults for the entire domain. The values under a specific entry under clusters
, set the defaults for cluster members of that cluster. The values under adminServer
or an entry under managedServers
, set the values for that specific server. Values from the domain scope and values from the cluster (for cluster members) are merged with or overridden by the setting for the specific server depending on the element. See Startup and shutdown for details about serverStartPolicy
combinations.
Elements related to the customization of liveness and readiness probes:
For additional domain resource attribute reference material, see Domain resource attribute references.
You can use the following environment variables to specify JVM memory and JVM option arguments to WebLogic Server Managed Server and Node Manager instances:
JAVA_OPTIONS
: Java options for starting WebLogic Server.USER_MEM_ARGS
: JVM memory arguments for starting WebLogic Server.NODEMGR_JAVA_OPTIONS
: Java options for starting a Node Manager instance.NODEMGR_MEM_ARGS
: JVM memory arguments for starting a Node Manager instance; this will take precedence over JAVA_OPTIONS
and USER_MEM_ARGS
.WLST_PROPERTIES
: System properties for WLST commands in introspector jobs or WebLogic Server instance containers.WLST_EXTRA_PROPERTIES
: System properties appended to WLST_PROPERTIES for WLST commands in introspector jobs or WebLogic Server instance containers.WLSDEPLOY_PROPERTIES
: System properties for WebLogic Deploy Tool commands during Model in Image introspector jobs or WebLogic Server instance containers.PRE_CLASSPATH
: Path(s) that are prepended to the WebLogic Server system classpath; delimit multiple paths with a colon :
.CLASSPATH
: Path(s) that are appended to the WebLogic Server system classpath; delimit multiple paths with a colon :
.Notes:
NODEMGR_JAVA_OPTIONS
and NODEMGR_MEM_ARGS
are defined:
NODEMGR_JAVA_OPTIONS
is not defined and JAVA_OPTIONS
is defined, then the JAVA_OPTIONS
value will be applied to the Node Manager instance.NODEMGR_MEM_ARGS
is not defined and USER_MEM_ARGS
is defined, then the USER_MEM_ARGS
value will be applied to the Node Manager instance.-Xms64m -Xmx100m -Djava.security.egd=file:/dev/./urandom
) will be applied to the Node Manager instance.USER_MEM_ARGS
and WLST_EXTRA_PROPERTIES
environment variables both default to -Djava.security.egd=file:/dev/./urandom
in all WebLogic Server pods and the WebLogic introspection job. They can be explicitly set to another value in your Domain YAML file using the env
attribute under the serverPod
configuration.NODEMGR_MEM_ARGS
, USER_MEM_ARGS
, and WLST_EXTRA_PROPERTIES
environment variables all include -Djava.security.egd=file:/dev/./urandom
by default. This helps to speed up the Node Manager and WebLogic Server startup on systems with low entropy, plus similarly helps to speed up introspection job usage of the WLST encrypt
command.JAVA_OPTIONS
and WLSDEPLOY_PROPERTIES
to disable Fast Application Notifications (FAN); see the Disable Fast Application Notifications FAQ for details.This example snippet illustrates how to add some of the above environment variables using the env
attribute under the serverPod
configuration in your Domain YAML file.
# Copyright (c) 2017, 2021, Oracle and/or its affiliates.
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
#
apiVersion: "weblogic.oracle/v8"
kind: Domain
metadata:
name: domain1
namespace: domains23
labels:
weblogic.domainUID: domain1
spec:
serverPod:
# an (optional) list of environment variable to be set on the servers
env:
- name: JAVA_OPTIONS
value: "-Dweblogic.StdoutDebugEnabled=false "
- name: USER_MEM_ARGS
value: "-Djava.security.egd=file:/dev/./urandom "
- name: NODEMGR_JAVA_OPTIONS
value: "-Dweblogic.StdoutDebugEnabled=false "
- name: NODEMGR_MEM_ARGS
value: "-Xms64m -Xmx100m -Djava.security.egd=file:/dev/./urandom "
- name: PRE_CLASSPATH
value: "/sample/path/prepended/to/weblogic/system/classpath:/another/prepended/path"
- name: CLASSPATH
value: "/sample/path/appended/to/weblogic/system/classpath:/another/appended/path"
The operator creates a Pod for each running WebLogic Server instance. This Pod will have a container, named weblogic-server
, based on the container image specified by the image
field. Additional Pod or container content can be specified using the elements under serverPod
. This includes Kubernetes sidecar and init containers, labels, annotations, volumes, volume mounts, scheduling constraints, including anti-affinity, resource requirements, or security context.
Customer provided labels and annotations may not begin with “weblogic” and the operator will generate the following labels:
weblogic.createdByOperator: "true"
weblogic.domainName: <domain-name>
, where <domain-name>
is the name of the WebLogic domainweblogic.domainUID: <uid>
, where <uid>
is the domain UID from the Domain resourceweblogic.serverName: <server-name>
, where <server-name>
is the name of the WebLogic Server instanceweblogic.clusterName: <cluster-name>
, where <cluster-name>
is the name of the cluster of which this instance is a member, if anyweblogic.domainRestartVersion: <restart-version>
, matches domain.spec.restartVersion
after the pod is up to date with this versionweblogic.introspectVersion: <introspect-version>
, matches domain.spec.introspectVersion
after the pod is up to date with this versionPrior to creating a Pod, the operator replaces variable references allowing the Pod content to be templates. The format of these variable references is $(VARIABLE_NAME)
where VARIABLE_NAME
is one of the variable names available in the container for the WebLogic Server instance. The default set of environment variables includes:
DOMAIN_NAME
: The WebLogic Server domain name.DOMAIN_UID
: The domain unique identifier.DOMAIN_HOME
: The domain home location as a file system path within the container.SERVER_NAME
: The WebLogic Server instance name.CLUSTER_NAME
: The WebLogic cluster name, if this is a cluster member.LOG_HOME
: If the `domain.spec.logHomeEnabled’ attribute is set to true, then this contains the WebLogic log location as a file system path within the containerThis example domain YAML file specifies that Pods for WebLogic Server instances in the cluster-1
cluster will have a per-Managed Server volume and volume mount (similar to a Kubernetes StatefulSet), an init container to initialize some files in that volume, and anti-affinity scheduling so that the server instances are scheduled, as much as possible, on different Nodes:
# Copyright (c) 2019, 2021, Oracle and/or its affiliates.
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
#
apiVersion: "weblogic.oracle/v8"
kind: Domain
metadata:
name: domain1
namespace: domains23
labels:
weblogic.domainUID: domain1
spec:
domainHome: /u01/oracle/user_projects/domains/domain1
domainHomeSourceType: Image
image: "phx.ocir.io/weblogick8s/my-domain-home-in-image:12.2.1.4"
imagePullPolicy: "IfNotPresent"
imagePullSecrets:
- name: ocirsecret
webLogicCredentialsSecret:
name: domain1-weblogic-credentials
includeServerOutInPodLog: true
serverStartPolicy: "IF_NEEDED"
serverPod:
env:
- name: JAVA_OPTIONS
value: "-Dweblogic.StdoutDebugEnabled=false"
- name: USER_MEM_ARGS
value: "-Djava.security.egd=file:/dev/./urandom "
adminServer:
serverStartState: "RUNNING"
clusters:
- clusterName: cluster-1
serverStartState: "RUNNING"
serverPod:
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchExpressions:
- key: "weblogic.clusterName"
operator: In
values:
- $(CLUSTER_NAME)
topologyKey: "kubernetes.io/hostname"
volumes:
- name: $(SERVER_NAME)-volume
emptyDir: {}
volumeMounts:
- mountPath: /server-volume
name: $(SERVER_NAME)-volume
initContainers:
- name: volumeinit
image: "oraclelinux:7-slim"
imagePullPolicy: IfNotPresent
command: ["/usr/bin/sh"]
args: ["echo", "Replace with command to initialize files in /init-volume"]
volumeMounts:
- mountPath: /init-volume
name: $(SERVER_NAME)-volume
replicas: 2
The operator uses an “introspection” job to discover details about the WebLogic domain configuration, such as the list of clusters and network access points. The Job Pod for the introspector is generated using the serverPod
entries for the Administration Server. Because the Administration Server name is not known until the introspection step is complete, the value of the $(SERVER_NAME)
variable for the introspection job will be “introspector”.