From d4525e6c9c10c6c1446d586c28096a31ac998483 Mon Sep 17 00:00:00 2001 From: Leo Christy Jesuraj Date: Fri, 27 Sep 2019 18:38:17 -0400 Subject: [PATCH] Documentation for kAppNav support + fix readme (#135) * Documentation for kAppNav support + fix readme * Documentation update + 0.2.0 release * Update changelog and user guide * Update image version + doc change --- CHANGELOG.md | 6 +- .../0.2.0/appsody-app-cluster-rbac.yaml | 82 +++++ deploy/releases/0.2.0/appsody-app-crd.yaml | 340 ++++++++++++++++++ .../releases/0.2.0/appsody-app-operator.yaml | 116 ++++++ deploy/releases/0.2.0/readme.md | 69 ++++ deploy/releases/daily/readme.md | 13 +- doc/user-guide.md | 60 ++-- 7 files changed, 656 insertions(+), 30 deletions(-) create mode 100644 deploy/releases/0.2.0/appsody-app-cluster-rbac.yaml create mode 100644 deploy/releases/0.2.0/appsody-app-crd.yaml create mode 100644 deploy/releases/0.2.0/appsody-app-operator.yaml create mode 100644 deploy/releases/0.2.0/readme.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b88bb04..a85022f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,11 +10,14 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +## [0.2.0] + ### Added - Support for watching multiple namespaces by setting `WATCH_NAMESPACE` to a comma-separated list of namespaces. ([#114](https://github.com/appsody/appsody-operator/issues/114)) - Allow users to add new labels or override default labels for resources created by the operator via setting labels on `AppsodyApplication` CRs. ([#118](https://github.com/appsody/appsody-operator/issues/118)) - Support for automatically creating and configuring `ServiceMonitor` resource for integration with Prometheus Operator. ([#125](https://github.com/appsody/appsody-operator/issues/125)) +- Automatically configure the `AppsodyApplication`'s Kubernetes resources to allow automatic creation of an application definition by [kAppNav](https://kappnav.io/), Kubernetes Application Navigator. ([#128](https://github.com/appsody/appsody-operator/issues/128),[#135](https://github.com/appsody/appsody-operator/issues/135)) ### Changed @@ -30,5 +33,6 @@ All notable changes to this project will be documented in this file. The initial release of the Appsody Operator 🎉🥳 -[Unreleased]: https://github.com/appsody/appsody-operator/compare/v0.1.0...HEAD +[Unreleased]: https://github.com/appsody/appsody-operator/compare/v0.2.0...HEAD +[0.2.0]: https://github.com/appsody/appsody-operator/releases/tag/v0.2.0 [0.1.0]: https://github.com/appsody/appsody-operator/releases/tag/v0.1.0 \ No newline at end of file diff --git a/deploy/releases/0.2.0/appsody-app-cluster-rbac.yaml b/deploy/releases/0.2.0/appsody-app-cluster-rbac.yaml new file mode 100644 index 0000000..1427c26 --- /dev/null +++ b/deploy/releases/0.2.0/appsody-app-cluster-rbac.yaml @@ -0,0 +1,82 @@ +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + creationTimestamp: null + name: appsody-operator-APPSODY_OPERATOR_NAMESPACE +rules: +- apiGroups: + - "" + resources: + - pods + - services + - endpoints + - persistentvolumeclaims + - events + - configmaps + - secrets + - serviceaccounts + verbs: + - '*' +- apiGroups: + - apps + resources: + - deployments + - daemonsets + - replicasets + - statefulsets + verbs: + - '*' +- apiGroups: + - autoscaling + resources: + - horizontalpodautoscalers + verbs: + - '*' +- apiGroups: + - monitoring.coreos.com + resources: + - servicemonitors + verbs: + - '*' +- apiGroups: + - apps + resourceNames: + - appsody-operator + resources: + - deployments/finalizers + verbs: + - update +- apiGroups: + - appsody.dev + resources: + - '*' + verbs: + - '*' +- apiGroups: + - route.openshift.io + attributeRestrictions: null + resources: + - routes + verbs: + - '*' +- apiGroups: + - serving.knative.dev + attributeRestrictions: null + resources: + - services + verbs: + - '*' +--- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: appsody-operator-APPSODY_OPERATOR_NAMESPACE +subjects: +- kind: ServiceAccount + name: appsody-operator + namespace: APPSODY_OPERATOR_NAMESPACE +roleRef: + kind: ClusterRole + name: appsody-operator-APPSODY_OPERATOR_NAMESPACE + apiGroup: rbac.authorization.k8s.io \ No newline at end of file diff --git a/deploy/releases/0.2.0/appsody-app-crd.yaml b/deploy/releases/0.2.0/appsody-app-crd.yaml new file mode 100644 index 0000000..b6f4c63 --- /dev/null +++ b/deploy/releases/0.2.0/appsody-app-crd.yaml @@ -0,0 +1,340 @@ +apiVersion: apiextensions.k8s.io/v1beta1 +kind: CustomResourceDefinition +metadata: + name: appsodyapplications.appsody.dev +spec: + additionalPrinterColumns: + - JSONPath: .spec.applicationImage + description: Absolute name of the deployed image containing registry and tag + name: Image + type: string + - JSONPath: .spec.expose + description: Specifies whether deployment is exposed externally via default Route + name: Exposed + type: boolean + - JSONPath: .status.conditions[?(@.type=='Reconciled')].status + description: Status of the reconcile condition + name: Reconciled + type: string + - JSONPath: .status.conditions[?(@.type=='Reconciled')].reason + description: Reason for the failure of reconcile condition + name: Reason + priority: 1 + type: string + - JSONPath: .status.conditions[?(@.type=='Reconciled')].message + description: Failure message from reconcile condition + name: Message + priority: 1 + type: string + - JSONPath: .metadata.creationTimestamp + description: Age of the resource + name: Age + type: date + group: appsody.dev + names: + kind: AppsodyApplication + listKind: AppsodyApplicationList + plural: appsodyapplications + singular: appsodyapplication + scope: Namespaced + subresources: + status: {} + validation: + openAPIV3Schema: + properties: + apiVersion: + description: 'APIVersion defines the versioned schema of this representation + of an object. Servers should convert recognized schemas to the latest + internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#resources' + type: string + kind: + description: 'Kind is a string value representing the REST resource this + object represents. Servers may infer this from the endpoint the client + submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds' + type: string + metadata: + type: object + spec: + properties: + applicationImage: + type: string + architecture: + items: + type: string + type: array + autoscaling: + properties: + maxReplicas: + format: int32 + minimum: 1 + type: integer + minReplicas: + format: int32 + type: integer + targetCPUUtilizationPercentage: + format: int32 + type: integer + type: object + createAppDefinition: + type: boolean + createKnativeService: + type: boolean + env: + items: + type: object + type: array + envFrom: + items: + type: object + type: array + expose: + type: boolean + livenessProbe: + type: object + monitoring: + properties: + endpoints: + items: + properties: + basicAuth: + description: 'BasicAuth allow an endpoint to authenticate + over basic authentication More info: https://prometheus.io/docs/operating/configuration/#endpoints' + properties: + password: + description: The secret that contains the password for + authenticate + type: object + username: + description: The secret that contains the username for + authenticate + type: object + type: object + bearerTokenFile: + description: File to read bearer token for scraping targets. + type: string + honorLabels: + description: HonorLabels chooses the metric's labels on collisions + with target labels. + type: boolean + interval: + description: Interval at which metrics should be scraped + type: string + metricRelabelings: + description: MetricRelabelConfigs to apply to samples before + ingestion. + items: + properties: + action: + description: Action to perform based on regex matching. + Default is 'replace' + type: string + modulus: + description: Modulus to take of the hash of the source + label values. + format: int64 + type: integer + regex: + description: Regular expression against which the extracted + value is matched. defailt is '(.*)' + type: string + replacement: + description: Replacement value against which a regex + replace is performed if the regular expression matches. + Regex capture groups are available. Default is '$1' + type: string + separator: + description: Separator placed between concatenated source + label values. default is ';'. + type: string + sourceLabels: + description: The source labels select values from existing + labels. Their content is concatenated using the configured + separator and matched against the configured regular + expression for the replace, keep, and drop actions. + items: + type: string + type: array + targetLabel: + description: Label to which the resulting value is written + in a replace action. It is mandatory for replace actions. + Regex capture groups are available. + type: string + type: object + type: array + params: + additionalProperties: + items: + type: string + type: array + description: Optional HTTP URL parameters + type: object + path: + description: HTTP path to scrape for metrics. + type: string + port: + description: Name of the service port this endpoint refers + to. Mutually exclusive with targetPort. + type: string + proxyUrl: + description: ProxyURL eg http://proxyserver:2195 Directs scrapes + to proxy through this endpoint. + type: string + relabelings: + description: 'RelabelConfigs to apply to samples before ingestion. + More info: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#relabel_config' + items: + properties: + action: + description: Action to perform based on regex matching. + Default is 'replace' + type: string + modulus: + description: Modulus to take of the hash of the source + label values. + format: int64 + type: integer + regex: + description: Regular expression against which the extracted + value is matched. defailt is '(.*)' + type: string + replacement: + description: Replacement value against which a regex + replace is performed if the regular expression matches. + Regex capture groups are available. Default is '$1' + type: string + separator: + description: Separator placed between concatenated source + label values. default is ';'. + type: string + sourceLabels: + description: The source labels select values from existing + labels. Their content is concatenated using the configured + separator and matched against the configured regular + expression for the replace, keep, and drop actions. + items: + type: string + type: array + targetLabel: + description: Label to which the resulting value is written + in a replace action. It is mandatory for replace actions. + Regex capture groups are available. + type: string + type: object + type: array + scheme: + description: HTTP scheme to use for scraping. + type: string + scrapeTimeout: + description: Timeout after which the scrape is ended + type: string + targetPort: + anyOf: + - type: string + - type: integer + description: Name or number of the target port of the endpoint. + Mutually exclusive with port. + tlsConfig: + description: TLS configuration to use when scraping the endpoint + properties: + caFile: + description: The CA cert to use for the targets. + type: string + certFile: + description: The client cert file for the targets. + type: string + insecureSkipVerify: + description: Disable target certificate validation. + type: boolean + keyFile: + description: The client key file for the targets. + type: string + serverName: + description: Used to verify the hostname for the targets. + type: string + type: object + type: object + type: array + labels: + additionalProperties: + type: string + type: object + type: object + pullPolicy: + type: string + pullSecret: + type: string + readinessProbe: + type: object + replicas: + format: int32 + type: integer + resourceConstraints: + type: object + service: + properties: + annotations: + additionalProperties: + type: string + type: object + port: + format: int32 + maximum: 65536 + minimum: 1 + type: integer + type: + type: string + type: object + serviceAccountName: + type: string + stack: + type: string + storage: + properties: + mountPath: + type: string + size: + pattern: ^([+-]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$ + type: string + volumeClaimTemplate: + type: object + type: object + version: + type: string + volumeMounts: + items: + type: object + type: array + volumes: + items: + type: object + type: array + required: + - applicationImage + type: object + status: + properties: + conditions: + items: + properties: + lastTransitionTime: + format: date-time + type: string + lastUpdateTime: + format: date-time + type: string + message: + type: string + reason: + type: string + status: + type: string + type: + type: string + type: object + type: array + type: object + version: v1beta1 + versions: + - name: v1beta1 + served: true + storage: true diff --git a/deploy/releases/0.2.0/appsody-app-operator.yaml b/deploy/releases/0.2.0/appsody-app-operator.yaml new file mode 100644 index 0000000..1d4b08e --- /dev/null +++ b/deploy/releases/0.2.0/appsody-app-operator.yaml @@ -0,0 +1,116 @@ +apiVersion: v1 +kind: ServiceAccount +metadata: + name: appsody-operator +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + creationTimestamp: null + name: appsody-operator +rules: +- apiGroups: + - "" + resources: + - pods + - services + - endpoints + - persistentvolumeclaims + - events + - configmaps + - secrets + - serviceaccounts + verbs: + - '*' +- apiGroups: + - apps + resources: + - deployments + - daemonsets + - replicasets + - statefulsets + verbs: + - '*' +- apiGroups: + - autoscaling + resources: + - horizontalpodautoscalers + verbs: + - '*' +- apiGroups: + - monitoring.coreos.com + resources: + - servicemonitors + verbs: + - '*' +- apiGroups: + - apps + resourceNames: + - appsody-operator + resources: + - deployments/finalizers + verbs: + - update +- apiGroups: + - appsody.dev + resources: + - '*' + verbs: + - '*' +- apiGroups: + - route.openshift.io + attributeRestrictions: null + resources: + - routes + verbs: + - '*' +- apiGroups: + - serving.knative.dev + attributeRestrictions: null + resources: + - services + verbs: + - '*' +--- +kind: RoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: appsody-operator +subjects: +- kind: ServiceAccount + name: appsody-operator +roleRef: + kind: Role + name: appsody-operator + apiGroup: rbac.authorization.k8s.io +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: appsody-operator +spec: + replicas: 1 + selector: + matchLabels: + name: appsody-operator + template: + metadata: + labels: + name: appsody-operator + spec: + serviceAccountName: appsody-operator + containers: + - name: appsody-operator + image: appsody/application-operator:0.2.0 + command: + - appsody-operator + imagePullPolicy: Always + env: + - name: WATCH_NAMESPACE + value: APPSODY_WATCH_NAMESPACE + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: OPERATOR_NAME + value: "appsody-operator" diff --git a/deploy/releases/0.2.0/readme.md b/deploy/releases/0.2.0/readme.md new file mode 100644 index 0000000..c7cd7d6 --- /dev/null +++ b/deploy/releases/0.2.0/readme.md @@ -0,0 +1,69 @@ +# Appsody Operator + +## Changelog + +All notable changes are documented in [Changelog](/CHANGELOG.md#0.2.0) + +## Installation + +The Appsody Operator can be installed to: + +- watch own namespace +- watch another namespace +- watch multiple namespaces +- watch all namespaces in the cluster + +Appropriate cluster role and binding are required to watch another namespace, watch multiple namespaces or watch all namespaces. + +--- + +1. Install `AppsodyApplication` Custom Resource Definition (CRD). This needs to be done only ONCE per cluster: + + ```console + kubectl apply -f https://raw.githubusercontent.com/appsody/appsody-operator/master/deploy/releases/0.2.0/appsody-app-crd.yaml + ``` + +2. Install the Appsody Operator: + + **Important: In Step 2.1, ensure that you replace `` and `` with proper values:** + + 2.1. Set operator namespace and the namespace to watch: + + - To watch all namespaces in the cluster, set `WATCH_NAMESPACE='""'` + - To watch multiple namespaces in the cluster, set `WATCH_NAMESPACE` to a comma-separated list of namespaces e.g. `WATCH_NAMESPACE=my-appsody-ns-1,my-appsody-ns-2,my-appsody-ns-3` + + ```console + OPERATOR_NAMESPACE= + WATCH_NAMESPACE= + ``` + + 2.2. _Optional_: Install cluster-level role-based access. This step can be skipped if the operator is only watching own namespace: + + ```console + curl -L https://raw.githubusercontent.com/appsody/appsody-operator/master/deploy/releases/0.2.0/appsody-app-cluster-rbac.yaml \ + | sed -e "s/APPSODY_OPERATOR_NAMESPACE/${OPERATOR_NAMESPACE}/" \ + | kubectl apply -f - + ``` + + 2.3. Install the operator: + + ```console + curl -L https://raw.githubusercontent.com/appsody/appsody-operator/master/deploy/releases/0.2.0/appsody-app-operator.yaml \ + | sed -e "s/APPSODY_WATCH_NAMESPACE/${WATCH_NAMESPACE}/" \ + | kubectl apply -n ${OPERATOR_NAMESPACE} -f - + ``` + +## Uninstallation + +To uninstall the operator, run commands from Step 2.3 first and then Step 2.2 (if applicable), but after replacing `kubectl apply` with `kubectl delete`. + +To delete the CRD, run command from Step 1, but after replacing `kubectl apply` with `kubectl delete`. + +_Deleting the CRD will also delete all `AppsodyApplication` in the cluster_ + +## Current Limitations + +- Knative support is limited. Values specified for `autoscaling`, `resources` and `replicas` parameters would not apply for Knative when enabled using `createKnativeService` parameter. +- The auto-creation of an application definition by kAppNav is not supported when Knative is enabled. +- Monitoring feature does not support integration with Knative Service. Prometheus Operator is required to use ServiceMonitor. +- After the initial deployment of `AppsodyApplication`, any changes to its labels would be applied only when one of the parameters from `spec` is updated. diff --git a/deploy/releases/daily/readme.md b/deploy/releases/daily/readme.md index 773f92c..0bb9991 100644 --- a/deploy/releases/daily/readme.md +++ b/deploy/releases/daily/readme.md @@ -4,14 +4,12 @@ The Appsody Operator can be installed to: -- watch its own namespace +- watch own namespace - watch another namespace - watch multiple namespaces - watch all namespaces in the cluster -Appropriate cluster role and binding are required to watch another namespace, watch multiple namespaces or to watch all namespaces. - -_Limitation: Operator cannot be installed to watch multiple namespaces_ +Appropriate cluster role and binding are required to watch another namespace, watch multiple namespaces or watch all namespaces. --- @@ -35,7 +33,7 @@ _Limitation: Operator cannot be installed to watch multiple namespaces_ WATCH_NAMESPACE= ``` - 2.2. _Optional_: Install cluster-level role-based access. This step can be skipped if the operator is only watching its own namespace: + 2.2. _Optional_: Install cluster-level role-based access. This step can be skipped if the operator is only watching own namespace: ```console curl -L https://raw.githubusercontent.com/appsody/appsody-operator/master/deploy/releases/daily/appsody-app-cluster-rbac.yaml \ @@ -61,4 +59,7 @@ _Deleting the CRD will also delete all `AppsodyApplication` in the cluster_ ## Current Limitations -- Knative support is limited. Values specified for `autoscaling`, `resources` and `replicas` parameters would not apply for Knative when enabled using `createKnativeService` parameter. \ No newline at end of file +- Knative support is limited. Values specified for `autoscaling`, `resources` and `replicas` parameters would not apply for Knative when enabled using `createKnativeService` parameter. +- The auto-creation of an application definition by kAppNav is not supported when Knative is enabled. +- Monitoring feature does not support integration with Knative Service. Prometheus Operator is required to use ServiceMonitor. +- After the initial deployment of `AppsodyApplication`, any changes to its labels would be applied only when one of the parameters from `spec` is updated. \ No newline at end of file diff --git a/doc/user-guide.md b/doc/user-guide.md index e441be9..d3083d6 100644 --- a/doc/user-guide.md +++ b/doc/user-guide.md @@ -8,16 +8,16 @@ Use the instructions for one of the [releases](../deploy/releases) to install th The Appsody Operator can be installed to: -- watch its own namespace +- watch own namespace - watch another namespace - watch multiple namespaces - watch all namespaces in the cluster -Appropriate cluster roles and bindings are required to watch another namespace, watch multiple namespaces or to watch all namespaces. +Appropriate cluster roles and bindings are required to watch another namespace, watch multiple namespaces or watch all namespaces. ## Overview -The architecture of the Appsody Operator follows the basic controller pattern: the Operator container with the controller is deployed into a Pod and listens for incoming resources with `Kind: AppsodyApplication`. Creating a `AppsodyApplication` custom resource (CR) triggers the Appsody Operator to create, update or delete Kubernetes resources needed by the application to run on your cluster. +The architecture of the Appsody Operator follows the basic controller pattern: the Operator container with the controller is deployed into a Pod and listens for incoming resources with `Kind: AppsodyApplication`. Creating an `AppsodyApplication` custom resource (CR) triggers the Appsody Operator to create, update or delete Kubernetes resources needed by the application to run on your cluster. Each instance of `AppsodyApplication` CR represents the application to be deployed on the cluster: @@ -49,6 +49,7 @@ Each `AppsodyApplication` CR must specify `applicationImage` parameter. Specifyi | Parameter | Description | |---|---| | `stack` | The name of the Appsody Application Stack that produced this application image. | +| `version` | The current version of the application. Label `app.kubernetes.io/version` will be added to all resources when the version is defined. | | `serviceAccountName` | The name of the OpenShift service account to be used during deployment. | | `applicationImage` | The absolute name of the image to be deployed, containing the registry and the tag. | | `pullPolicy` | The policy used when pulling the image. One of: `Always`, `Never`, and `IfNotPresent`. | @@ -60,7 +61,7 @@ Each `AppsodyApplication` CR must specify `applicationImage` parameter. Specifyi | `createKnativeService` | A boolean to toggle the creation of Knative resources and usage of Knative serving. | | `expose` | A boolean that toggles the external exposure of this deployment via a Route or a Knative Route resource.| | `replicas` | The static number of desired replica pods that run simultaneously. | -| `autoscaling.maxReplicas` | Required field for autoscaling. Upper limit for the number of pods that can be set by the autoscaler. Cannot be lower than the minimum number of replicas. | +| `autoscaling.maxReplicas` | Required field for autoscaling. Upper limit for the number of pods that can be set by the autoscaler. It cannot be lower than the minimum number of replicas. | | `autoscaling.minReplicas` | Lower limit for the number of pods that can be set by the autoscaler. | | `autoscaling.targetCPUUtilizationPercentage` | Target average CPU utilization (represented as a percentage of requested CPU) over all the pods. | | `resourceConstraints.requests.cpu` | The minimum required CPU core. Specify integers, fractions (e.g. 0.5), or millicore values(e.g. 100m, where 100m is equivalent to .1 core). Required field for autoscaling. | @@ -73,11 +74,13 @@ Each `AppsodyApplication` CR must specify `applicationImage` parameter. Specifyi | `livenessProbe` | A YAML object configuring the [Kubernetes liveness probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/#define-a-liveness-http-request) that controls when Kubernetes needs to restart the pod.| | `volumes` | A YAML object representing a [pod volume](https://kubernetes.io/docs/concepts/storage/volumes). | | `volumeMounts` | A YAML object representing a [pod volumeMount](https://kubernetes.io/docs/concepts/storage/volumes/). | -| `storage.size` | A convenient field to set the size of the persisted storage. Can be overriden by the `storage.volumeClaimTemplate` property. | +| `storage.size` | A convenient field to set the size of the persisted storage. Can be overridden by the `storage.volumeClaimTemplate` property. | | `storage.mountPath` | The directory inside the container where this persisted storage will be bound to. | | `storage.volumeClaimTemplate` | A YAML object representing a [volumeClaimTemplate](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#components) component of a `StatefulSet`. | | `monitoring.labels` | Labels to set on [ServiceMonitor](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#servicemonitor). | -| `monitoring.endpoints` | A YAML snippet representing a array of [Endpoint](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#endpoint) component from ServiceMonitor. | +| `monitoring.endpoints` | A YAML snippet representing an array of [Endpoint](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#endpoint) component from ServiceMonitor. | +| `createAppDefinition` | A boolean to toggle the automatic configuration of `AppsodyApplication`'s Kubernetes resources to allow creation of an application definition by [kAppNav](https://kappnav.io/). The default value is `true`. See [Application Navigator](#kubernetes-application-navigator-(kappnav)-support) for more information. | + ### Basic usage To deploy a Docker image containing an Appsody based application to a Kubernetes environment you can use the following CR: @@ -92,7 +95,7 @@ spec: applicationImage: quay.io/my-repo/my-app:1.0 ``` -Both `stack` and `applicationImage` values are required to be defined in an `AppsodyApplication` CR. `stack` should be the same value as the [Appsody application stack](https://github.com/appsody/stacks) you used to created your application. +The `applicationImage` value is required to be defined in `AppsodyApplication` CR. The `stack` should be the same value as the [Appsody application stack](https://github.com/appsody/stacks) you used to create your application. ### Service account @@ -104,7 +107,7 @@ If applications require specific permissions but still want the operator to crea ### Labels -By default, the operator adds the following labels into all resources created for an `AppsodyApplication` CR: `app.kubernetes.io/name`, `app.kubernetes.io/managed-by`, `app.appsody.dev/stack`. You can set new labels in addition to the pre-existing ones or overwrite them, excluding the `app.kubernetes.io/name` label. To set labels, specify them in your CR as key/value pairs. +By default, the operator adds the following labels into all resources created for an `AppsodyApplication` CR: `app.kubernetes.io/name`, `app.kubernetes.io/managed-by`, `app.appsody.dev/stack` and `app.kubernetes.io/version` (only when `version` is defined). You can set new labels in addition to the pre-existing ones or overwrite them, excluding the `app.kubernetes.io/name` label. To set labels, specify them in your CR as key/value pairs. ```yaml apiVersion: appsody.dev/v1beta1 @@ -118,6 +121,8 @@ spec: applicationImage: quay.io/my-repo/my-app:1.0 ``` +_After the initial deployment of `AppsodyApplication`, any changes to its labels would be applied only when one of the parameters from `spec` is updated._ + ### Environment variables You can set environment variables for your application container. To set environment variables, specify `env` and/or `envFrom` fields in your CR. The environment variables can come directly from key/value pairs, `ConfigMap`s or `Secret`s. @@ -150,7 +155,7 @@ spec: name: env-secrets ``` -Use `envFrom` to define all data in a `ConfigMap` or a `Secret` as environment variables in a container. Keys from `ConfigMap` or `Secret` resources, become environment variable name in your container. +Use `envFrom` to define all data in a `ConfigMap` or a `Secret` as environment variables in a container. Keys from `ConfigMap` or `Secret` resources become environment variable name in your container. ### High availability @@ -159,8 +164,8 @@ Run multiple instances of your application for high availability using one of th _OR_ - - configure auto scaling to create (and delete) instances based on resource consumption using the `autoscaling` parameter. - - Parameters `autoscaling.maxReplicas` and `resourceConstraints.requests.cpu` MUST be specified for auto scaling. + - configure auto-scaling to create (and delete) instances based on resource consumption using the `autoscaling` parameter. + - Parameters `autoscaling.maxReplicas` and `resourceConstraints.requests.cpu` MUST be specified for auto-scaling. ### Persistence @@ -172,7 +177,7 @@ Users also can provide mount points for their application. There are 2 ways to e With the `AppsodyApplication` CR definition below the operator will create `PersistentVolumeClaim` called `pvc` with the size of `1Gi` and `ReadWriteOnce` access mode. -Operator will also create a volume mount for the `StatefulSet` mounting to `/data` folder. You can use `volumeMounts` field instead of `storage.mountPath` if you require to persist more then one folder. +The operator will also create a volume mount for the `StatefulSet` mounting to `/data` folder. You can use `volumeMounts` field instead of `storage.mountPath` if you require to persist more then one folder. ```yaml apiVersion: appsody.dev/v1beta1 @@ -189,7 +194,7 @@ spec: #### Advanced storage -Operator allows users to provide entire `volumeClaimTemplate` for full control over automatically created `PersistentVolumeClaim`. +Appsody Operator allows users to provide entire `volumeClaimTemplate` for full control over automatically created `PersistentVolumeClaim`. It is also possible to create multiple volume mount points for persistent volume using `volumeMounts` field as shown below. You can still use `storage.mountPath` if you require only a single mount point. @@ -222,11 +227,13 @@ spec: ``` ### Monitoring -Appsody Operator can create a `ServiceMonitor` resource to integrate with `Prometheus Operator` +Appsody Operator can create a `ServiceMonitor` resource to integrate with `Prometheus Operator`. + +_This feature does not support integration with Knative Service. Prometheus Operator is required to use ServiceMonitor._ #### Basic monitoring specification -As minimum a label needs to be provided that Prometheus expects to be set on `ServiceMonitor` objects. In this case it is `apps-prometheus` +At minimum, a label needs to be provided that Prometheus expects to be set on `ServiceMonitor` objects. In this case, it is `apps-prometheus`. ```yaml apiVersion: appsody.dev/v1beta1 @@ -243,7 +250,7 @@ spec: #### Advanced monitoring specification -For advanced scenarios it is possible to set many `ServicerMonitor` settings such as authentication sercret using [Prometheus Endpoint](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#endpoint) +For advanced scenarios, it is possible to set many `ServicerMonitor` settings such as authentication secret using [Prometheus Endpoint](https://github.com/coreos/prometheus-operator/blob/master/Documentation/api.md#endpoint) ```yaml apiVersion: appsody.dev/v1beta1 @@ -269,6 +276,8 @@ spec: insecureSkipVerify: true ``` +__ + ### Knative support Appsody Operator can deploy serverless applications with [Knative](https://knative.dev/docs/) on a Kubernetes cluster. To achieve this, the operator creates a [Knative `Service`](https://github.com/knative/serving/blob/master/docs/spec/spec.md#service) resource which manages the whole life cycle of a workload. @@ -286,7 +295,7 @@ spec: createKnativeService: true ``` -By setting this parameter, the operator creates a Knative service in the cluster and populates the resource with applicable `AppsodyApplication` fields. Also it ensures non-Knative resources including Kubernetes `Service`, `Route`, `Deployment` and etc. are deleted. +By setting this parameter, the operator creates a Knative service in the cluster and populates the resource with applicable `AppsodyApplication` fields. Also, it ensures non-Knative resources including Kubernetes `Service`, `Route`, `Deployment` and etc. are deleted. The CRD fields that are used to populate the Knative service resource includes `applicationImage`, `serviceAccountName`, `livenessProbe`, `readinessProbe`, `service.Port`, `volumes`, `volumeMounts`, `env`, `envFrom`, `pullSecret` and `pullPolicy`. @@ -333,7 +342,7 @@ spec: expose: true ``` -When `expose` is **not** set to `true`, the Knative service is labelled with `serving.knative.dev/visibility=cluster-local` which makes the Knative route to only be available on the cluster-local network (and not on the public Internet). However, if `expose` is set `true`, the Knative route would be accessible externally. +When `expose` is **not** set to `true`, the Knative service is labeled with `serving.knative.dev/visibility=cluster-local` which makes the Knative route to only be available on the cluster-local network (and not on the public Internet). However, if `expose` is set `true`, the Knative route would be accessible externally. To configure secure HTTPS connections for your deployment, see [Configuring HTTPS with TLS certificates](https://knative.dev/docs/serving/using-a-tls-cert/) for more information. @@ -358,8 +367,7 @@ spec: applicationImage: quay.io/my-repo/my-app:1.0 ``` -Since in the `AppsodyApplicaiton` resource service `port` and `type` are not set, they will be looked up in the defaults config map and added to the resource. -and will be set according to `stack` field. If the `appsody-operator-defaults` doesn't have the `stack` with particular name defined operator will use `generic` stack default values. +Since in the `AppsodyApplication` resource service `port` and `type` are not set, they will be looked up in the default `ConfigMap` and added to the resource. It will be set according to the `stack` field. If the `appsody-operator-defaults` doesn't have the `stack` with a particular name defined then the operator will use `generic` stack's default values. After defaults are applied: @@ -379,9 +387,7 @@ spec: #### Stack Constants ConfigMap -[`appsody-operator-constants`](../deploy/stack_constants.yaml) ConfigMap contains the constant values for each stack. This values will always be used over the ones -that users provide. This can be used to limit user ability to control certain fields such as `expose`. -It also provides ability to set environment variables that are always required. +[`appsody-operator-constants`](../deploy/stack_constants.yaml) ConfigMap contains the constant values for each stack. These values will always be used over the ones that users provide. This can be used to limit user's ability to control certain fields such as `expose`. It also provides the ability to set environment variables that are always required. Input resource: @@ -418,6 +424,14 @@ spec: value: url ``` +### Kubernetes Application Navigator (kAppNav) support + +By default, Appsody Operator configures the Kubernetes resources it generates to allow automatic creation of an application definition by [kAppNav](https://kappnav.io/), Kubernetes Application Navigator. You can easily view and manage the deployed resources that comprise your application using Application Navigator. You can disable auto-creation by setting `createAppDefinition` to `false`. + +To join an existing application definition, disable auto-creation and set the label(s) needed to join the application on `AppsodyApplication` CR. See [Labels](#labels) section for more information. + +_This feature is only available if you have kAppNav installed on your cluster. Auto creation of an application definition is not supported when Knative service is created_ + ### Troubleshooting See the [troubleshooting guide](troubleshooting.md) for information on how to investigate and resolve deployment problems.