From 5bed27c716683099b1ec1ac78f0150c548e66fa6 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Wed, 4 May 2022 11:09:37 -0500 Subject: [PATCH] [SRVKS-892]: Add init container docs --- modules/serverless-admin-init-containers.adoc | 44 +++++++++++++++++ modules/serverless-config-emptydir.adoc | 10 ++-- modules/serverless-init-containers-apps.adoc | 47 +++++++++++++++++++ .../admin_guide/serverless-configuration.adoc | 4 ++ .../develop/serverless-applications.adoc | 5 +- 5 files changed, 105 insertions(+), 5 deletions(-) create mode 100644 modules/serverless-admin-init-containers.adoc create mode 100644 modules/serverless-init-containers-apps.adoc diff --git a/modules/serverless-admin-init-containers.adoc b/modules/serverless-admin-init-containers.adoc new file mode 100644 index 000000000000..08bc57751480 --- /dev/null +++ b/modules/serverless-admin-init-containers.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * /serverless/admin_guide/serverless-configuration.adoc + +:_content-type: PROCEDURE +[id="serverless-admin-init-containers_{context}"] += Enabling init containers + +link:https://kubernetes.io/docs/concepts/workloads/pods/init-containers/[Init containers] are specialized containers that are run before application containers in a pod. They are generally used to implement initialization logic for an application, which may include running setup scripts or downloading required configurations. You can enable the use of init containers for Knative services by modifying the `KnativeServing` custom resource (CR). + +[NOTE] +==== +Init containers may cause longer application start-up times and should be used with caution for serverless applications, which are expected to scale up and down frequently. +==== + +.Prerequisites + +* You have installed {ServerlessOperatorName} and Knative Serving on your cluster. + +ifdef::openshift-enterprise[] +* You have cluster administrator permissions. +endif::[] + +ifdef::openshift-dedicated[] +* You have cluster or dedicated administrator permissions. +endif::[] + +.Procedure + +* Enable the use of init containers by adding the `kubernetes.podspec-init-containers` flag to the `KnativeServing` CR: ++ +.Example KnativeServing CR +[source,yaml] +---- +apiVersion: operator.knative.dev/v1alpha1 +kind: KnativeServing +metadata: + name: knative-serving +spec: + config: + features: + kubernetes.podspec-init-containers: enabled +... +---- diff --git a/modules/serverless-config-emptydir.adoc b/modules/serverless-config-emptydir.adoc index ba616353e85b..b268dd1bfdaf 100644 --- a/modules/serverless-config-emptydir.adoc +++ b/modules/serverless-config-emptydir.adoc @@ -9,14 +9,18 @@ `emptyDir` volumes are empty volumes that are created when a pod is created, and are used to provide temporary working disk space. `emptyDir` volumes are deleted when the pod they were created for is deleted. -The `"kubernetes.podspec-volumes-emptydir"` extension controls whether `emptyDir` volumes can be used with Knative Serving. To enable using `emptyDir` volumes, you must modify the `KnativeServing` custom resource (CR) to include the following YAML: +The `kubernetes.podspec-volumes-emptydir` extension controls whether `emptyDir` volumes can be used with Knative Serving. To enable using `emptyDir` volumes, you must modify the `KnativeServing` custom resource (CR) to include the following YAML: +.Example KnativeServing CR [source,yaml] ---- -... +apiVersion: operator.knative.dev/v1alpha1 +kind: KnativeServing +metadata: + name: knative-serving spec: config: features: - "kubernetes.podspec-volumes-emptydir": enabled + kubernetes.podspec-volumes-emptydir: enabled ... ---- diff --git a/modules/serverless-init-containers-apps.adoc b/modules/serverless-init-containers-apps.adoc new file mode 100644 index 000000000000..b2c1762a46c1 --- /dev/null +++ b/modules/serverless-init-containers-apps.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// * /serverless/develop/serverless-applications.adoc + +:_content-type: PROCEDURE +[id="serverless-init-containers-apps_{context}"] += Configuring init containers + +link:https://kubernetes.io/docs/concepts/workloads/pods/init-containers/[Init containers] are specialized containers that are run before application containers in a pod. They are generally used to implement initialization logic for an application, which may include running setup scripts or downloading required configurations. + +[NOTE] +==== +Init containers may cause longer application start-up times and should be used with caution for serverless applications, which are expected to scale up and down frequently. +==== + +Multiple init containers are supported in a single Knative service spec. Knative provides a default, configurable naming template if a template name is not provided. The init containers template can be set by adding an appropriate value in a Knative `Service` object spec. + +.Prerequisites + +* {ServerlessOperatorName} and Knative Serving are installed on your cluster. + +* Before you can use init containers for Knative services, an administrator must add the `kubernetes.podspec-init-containers` flag to the `KnativeServing` custom resource (CR). See the {ServerlessProductName} "Global configuration" documentation for more information. + +.Procedure + +* Add the `initContainers` spec to a Knative `Service` object: ++ +.Example service spec +[source,yaml] +---- +apiVersion: serving.knative.dev/v1 +kind: Service +... +spec: + template: + spec: + initContainers: + - imagePullPolicy: IfNotPresent <1> + image: <2> + volumeMounts: <3> + - name: data + mountPath: /data +... +---- +<1> The link:https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy[image pull policy] when the image is downloaded. +<2> The URI for the init container image. +<3> The location where volumes are mounted within the container file system. diff --git a/serverless/admin_guide/serverless-configuration.adoc b/serverless/admin_guide/serverless-configuration.adoc index 0ca78a747a98..91cbb0f585de 100644 --- a/serverless/admin_guide/serverless-configuration.adoc +++ b/serverless/admin_guide/serverless-configuration.adoc @@ -16,7 +16,9 @@ The `spec.config` in the Knative custom resources have one `` entry for ea include::modules/serverless-channel-default.adoc[leveloffset=+1] // Knative Serving +// deployments include::modules/knative-serving-CR-system-deployments.adoc[leveloffset=+1] +// enable emptydirs include::modules/serverless-config-emptydir.adoc[leveloffset=+1] // global https redirect include::modules/serverless-https-redirect-global.adoc[leveloffset=+1] @@ -26,6 +28,8 @@ include::modules/serverless-url-scheme-external-routes.adoc[leveloffset=+1] include::modules/serverless-kourier-gateway-service-type.adoc[leveloffset=+1] // Enabling PVC for Serving include::modules/serverless-enabling-pvc-support.adoc[leveloffset=+1] +// enable init containers +include::modules/serverless-admin-init-containers.adoc[leveloffset=+1] ifdef::openshift-enterprise[] [id="additional-resources_knative-serving-CR-config"] diff --git a/serverless/develop/serverless-applications.adoc b/serverless/develop/serverless-applications.adoc index 93e9529733fb..82f9a79f5e7c 100644 --- a/serverless/develop/serverless-applications.adoc +++ b/serverless/develop/serverless-applications.adoc @@ -57,11 +57,12 @@ ifdef::openshift-enterprise[] // Using Knative services w/ restrictive NetworkPolicies include::modules/serverless-services-network-policies.adoc[leveloffset=+1] endif::[] -// should maybe move to admin guide? asked serving team +// move to admin guide, outside scope of this PR +// config init containers +include::modules/serverless-init-containers-apps.adoc[leveloffset=+1] // HTTPS redirection include::modules/serverless-https-redirect-service.adoc[leveloffset=+1] -// asked serving team why a user would need this for abstract rewrite, waiting for details [id="additional-resources_serverless-applications"] [role="_additional-resources"]