add docs

streamnative · Feb 27, 2025 · b75c254 · b75c254
1 parent 4742984
commit b75c254
Show file tree

Hide file tree

Showing 5 changed files with 253 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -133,6 +133,7 @@ In this tutorial, a Kubernetes namespace called `test` is used for examples, whi
 - [StreamNativeCloudConnection](docs/streamnative_cloud_connection.md)
 - [ComputeWorkspace](docs/compute_workspace.md)
 - [ComputeFlinkDeployment](docs/compute_flink_deployment.md)
+- [StreamNative Cloud Secret](docs/secret.md)
 
 # Contributing
 

diff --git a/config/samples/kustomization.yaml b/config/samples/kustomization.yaml
@@ -21,4 +21,12 @@ resources:
 - resource_v1alpha1_pulsarpermission.yaml
 - resource_v1alpha1_pulsargeoreplication.yaml
 - resource_v1alpha1_pulsarpackage.yaml
+- resource_v1alpha1_pulsarfunction.yaml
+- resource_v1alpha1_pulsarsink.yaml
+- resource_v1alpha1_pulsarsource.yaml
+- resource_v1alpha1_pulsarnsisolationpolicy.yaml
+- resource_v1alpha1_streamnativecloudconnection.yaml
+- resource_v1alpha1_computeworkspace.yaml
+- resource_v1alpha1_computeflinkdeployment.yaml
+- resource_v1alpha1_secret.yaml
 #+kubebuilder:scaffold:manifestskustomizesamples
diff --git a/config/samples/resource_v1alpha1_secret.yaml b/config/samples/resource_v1alpha1_secret.yaml
@@ -0,0 +1,27 @@
+# Copyright 2024 StreamNative
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: resource.streamnative.io/v1alpha1
+kind: Secret
+metadata:
+  name: test-secret
+  namespace: default
+spec:
+  apiServerRef:
+    name: test-connection
+  type: Opaque
+  data:
+    key: value
+  location: "useast1"
+  instanceName: "test-instance"
diff --git a/docs/compute_flink_deployment.md b/docs/compute_flink_deployment.md
@@ -15,6 +15,8 @@ The `ComputeFlinkDeployment` resource defines a Flink deployment in StreamNative
 | `template`           | VVP deployment template configuration                                                       | No*      |
 | `communityTemplate`  | Community deployment template configuration                                                 | No*      |
 | `defaultPulsarCluster`| Default Pulsar cluster to use for the deployment                                          | No       |
+| `configuration`      | Additional configuration for the Flink deployment, including environment variables and secrets | No       |
+| `imagePullSecrets`   | List of image pull secrets to use for the deployment                                       | No       |
 
 *Note: Either `template` or `communityTemplate` must be specified, but not both.
 
@@ -31,6 +33,27 @@ This inheritance mechanism allows you to:
 - Centralize API server configuration at the workspace level
 - Easily change API server configuration for multiple deployments by updating the workspace
 
+### Configuration Structure
+
+| Field     | Description                                                                                | Required |
+|-----------|--------------------------------------------------------------------------------------------|----------|
+| `envs`    | List of environment variables to set in the Flink deployment                               | No       |
+| `secrets` | List of secrets referenced to deploy with the Flink deployment                             | No       |
+
+#### EnvVar Structure
+
+| Field   | Description                                                                                | Required |
+|---------|--------------------------------------------------------------------------------------------|----------|
+| `name`  | Name of the environment variable                                                           | Yes      |
+| `value` | Value of the environment variable                                                          | Yes      |
+
+#### SecretReference Structure
+
+| Field       | Description                                                                                | Required |
+|-------------|--------------------------------------------------------------------------------------------|----------|
+| `name`      | Name of the ENV variable                                                                   | Yes      |
+| `valueFrom` | References a secret in the same namespace                                                  | Yes      |
+
 ### VVP Deployment Template
 
 | Field           | Description                                                                                | Required |
@@ -169,13 +192,84 @@ spec:
                 com.company: DEBUG
 ```
 
-2. Apply the YAML file:
+2. Create a ComputeFlinkDeployment with configuration and imagePullSecrets:
+
+```yaml
+apiVersion: resource.streamnative.io/v1alpha1
+kind: ComputeFlinkDeployment
+metadata:
+  name: resource-operator-v4
+  namespace: default
+spec:
+  apiServerRef:
+    name: test-connection
+  workspaceName: o-nn5f0-vvp
+  configuration:
+    envs:
+    - name: ENV_TEST
+      value: "test"
+    secrets:
+    - name: SECRET_PASSWORD
+      valueFrom:
+        name: my-secret
+        key: password
+  imagePullSecrets:
+  - name: resource-operator-secret-docker-hub
+  template:
+    syncingMode: PATCH
+    deployment:
+      userMetadata:
+        name: resource-operator-v4
+        namespace: default
+        displayName: resource-operator-v4
+      spec:
+        state: RUNNING
+        deploymentTargetName: o-nn5f0
+        maxJobCreationAttempts: 99
+        template:
+          metadata:
+            annotations:
+              flink.queryable-state.enabled: 'false'
+              flink.security.ssl.enabled: 'false'
+          spec:
+            artifact:
+              mainArgs: --runner=FlinkRunner --pulsarCluster=wstest --attachedMode=false
+              entryClass: com.example.DataTransformer
+              kind: JAR
+              flinkVersion: "1.18.1"
+              flinkImageTag: "1.18.1-stream3-scala_2.12-java17"
+              artifactImage: example/private:latest
+            flinkConfiguration:
+              classloader.resolve-order: parent-first
+              execution.checkpointing.externalized-checkpoint-retention: RETAIN_ON_CANCELLATION
+              execution.checkpointing.interval: 1min
+              execution.checkpointing.timeout: 10min
+              high-availability.type: kubernetes
+              state.backend: filesystem
+              taskmanager.memory.managed.fraction: '0.2'
+            parallelism: 1
+            numberOfTaskManagers: 1
+            resources:
+              jobmanager:
+                cpu: "1"
+                memory: 2G
+              taskmanager:
+                cpu: "1"
+                memory: 2G
+            logging:
+              loggingProfile: default
+              log4jLoggers:
+                "": DEBUG
+                com.company: DEBUG
+```
+
+3. Apply the YAML file:
 
 ```shell
 kubectl apply -f deployment.yaml
 ```
 
-3. Check the deployment status:
+4. Check the deployment status:
 
 ```shell
 kubectl get computeflinkdeployment operator-test-v1
@@ -188,7 +282,7 @@ NAME             READY   AGE
 operator-test-v1 True    1m
 ```
 
-2. Create a ComputeFlinkDeployment using Workspace's APIServerRef:
+5. Create a ComputeFlinkDeployment using Workspace's APIServerRef:
 
 ```yaml
 apiVersion: resource.streamnative.io/v1alpha1
@@ -253,6 +347,8 @@ You can update the deployment by modifying the YAML file and reapplying it. Most
 - Parallelism
 - Logging settings
 - Artifact configuration
+- Environment variables and secrets
+- Image pull secrets
 
 After applying changes, verify the status to ensure the deployment is updated properly.
 

diff --git a/docs/secret.md b/docs/secret.md
@@ -0,0 +1,118 @@
+# Secret
+
+## Overview
+
+The `Secret` resource defines a secret in StreamNative Cloud. It allows you to create and manage secrets in StreamNative Cloud that can be referenced and used by other resources, such as ComputeFlinkDeployment.
+
+## Specifications
+
+| Field | Description | Required |
+|-------|-------------|----------|
+| `apiServerRef` | Reference to the StreamNativeCloudConnection resource for API server access | Yes |
+| `instanceName` | Name of the instance this secret is for (e.g. pulsar-instance) | No |
+| `location` | Location of the secret | No |
+| `data` | Secret data, values should be base64 encoded | No* |
+| `secretRef` | Reference to a Kubernetes secret. When secretRef is set, it will be used to fetch the secret data, and data field will be ignored | No* |
+| `poolMemberName` | Pool member to deploy the secret | No |
+| `tolerations` | Tolerations for the secret | No |
+| `type` | Used to facilitate programmatic handling of secret data | No |
+
+*Note: Either `data` or `secretRef` must be specified.
+
+### KubernetesSecretReference Structure
+
+| Field | Description | Required |
+|-------|-------------|----------|
+| `namespace` | Namespace of the Kubernetes secret | Yes |
+| `name` | Name of the Kubernetes secret | Yes |
+
+### Toleration Structure
+
+| Field | Description | Required |
+|-------|-------------|----------|
+| `key` | Taint key that the toleration applies to. Empty means match all taint keys | No |
+| `operator` | Represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal | No |
+| `value` | Taint value the toleration matches to | No |
+| `effect` | Indicates the taint effect to match. Empty means match all taint effects | No |
+
+## Status
+
+| Field | Description |
+|-------|-------------|
+| `conditions` | List of status conditions for the secret |
+| `observedGeneration` | The last observed generation of the resource |
+
+## Example
+
+1. Create a Secret resource with direct data:
+
+```yaml
+apiVersion: resource.streamnative.io/v1alpha1
+kind: Secret
+metadata:
+  name: resource-operator-secret
+  namespace: default
+spec:
+  apiServerRef:
+    name: test-connection
+  data:
+    test-key: test-value
+  instanceName: wstest
+  location: us-central1
+```
+
+2. Create a Secret resource with Kubernetes Secret reference:
+
+```yaml
+apiVersion: resource.streamnative.io/v1alpha1
+kind: Secret
+metadata:
+  name: resource-operator-secret-docker-hub
+  namespace: default
+spec:
+  apiServerRef:
+    name: test-connection
+  secretRef:
+    name: regcred
+    namespace: default
+  instanceName: wstest
+  location: us-central1
+```
+
+3. Apply the YAML file:
+
+```shell
+kubectl apply -f secret.yaml
+```
+
+4. Check the secret status:
+
+```shell
+kubectl get secret.resource.streamnative.io resource-operator-secret
+```
+
+The secret is ready when the Ready condition is True:
+
+```shell
+NAME                     READY   AGE
+resource-operator-secret True    1m
+```
+
+## Update Secret
+
+You can update the secret by modifying the YAML file and reapplying it. Most fields can be updated, including:
+- Secret data
+- Kubernetes secret reference
+- Tolerations
+
+After applying changes, verify the status to ensure the secret is configured properly.
+
+## Delete Secret
+
+To delete a Secret resource:
+
+```shell
+kubectl delete secret.resource.streamnative.io resource-operator-secret
+```
+
+Note that deleting the secret will affect any resources that depend on it, such as ComputeFlinkDeployments. Make sure to handle any dependent resources appropriately before deletion.