This documentation and the Cisco Observability Platform functionalities it describes are subject to change. Data saved on the platform may disappear and APIs may change without notice.
zodiac:function
Description
Defines the integration point between your solution and an HTTP-based service endpoint on a Docker container that Solution Services loads and runs on the platform on your behalf. In other words, a zodiac:function is a configuration that exposes an HTTP service endpoint and is the interface to/from that endpoint. Usually, we simply refer to a zodiac:function as a function. The function and its underlying Docker image are somewhat synonymous, and the documentation may use these terms interchangeably. You can define multiple functions in a solution.
Subscribers to your solution can access any HTTP service endpoint that your solution's functions expose. These endpoints are accessible at https://{tenant-name}.{fso-platform-url}/rest/{solution-name}/{function-name}/{function-endpoint}.
Schema
{
"name": "function",
"allowedLayers": ["SOLUTION"],
"idGeneration": {
"generateRandomId": false,
"idGenerationMechanism": "{{layer.id}}:{{object.name}}",
"enforceGlobalUniqueness": false
},
"jsonSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Function Spec",
"description": "Definition of a Function",
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "function name",
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$",
"maxLength": 253
},
"image": {
"type": "string",
"description": "fully qualified image name"
},
"openAPI": {
"type": "string",
"description": "reference to the function's openAPI contract"
},
"envvars": {
"description": "data to be passed in as environment variables",
"type": "object",
"additionalProperties": {
"type": "string"
},
"minItems": 1
},
"secrets": {
"description": "secrets to be passed in to the function",
"type": "object",
"additionalProperties": {
"type": "string"
},
"minItems": 1
},
"imagePullSecrets": {
"type": "array",
"description": "names of image pull secrets to be added to the function's pod",
"items": {
"type": "string"
},
"minItems": 1
},
"resources": {
"type": "object",
"properties": {
"requests": {
"type": "object",
"additionalProperties": {
"type": "string",
"pattern": "^([+-]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$"
}
},
"limits": {
"type": "object",
"additionalProperties": {
"type": "string",
"pattern": "^([+-]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$"
}
}
},
"additionalProperties": false
},
"concurrency": {
"type": "object",
"properties": {
"softLimit": {
"type": "integer",
"minimum": 0
},
"hardLimit": {
"type": "integer",
"minimum": 0
},
"targetUtilizationPercentage": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"additionalProperties": false
},
"scaleBounds": {
"type": "object",
"properties": {
"lower": {
"type": "integer",
"minimum": 0,
"maximum": 1000
},
"upper": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"secretEnvvars": {
"type": "array",
"description": "[DEPRECATED] environment variables with values stored in a secret storage",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[A-Z_]{1,}[A-Z0-9_]{0,99}$"
},
"path": {
"type": "string",
"pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(/[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$",
"maxLength": 256
}
},
"required": [
"name",
"path"
]
},
"minItems": 1
},
"secretEnvvarsV2": {
"type": "array",
"description": "It is used to set environment variables with values from an object of type 'solutionSecret'. This object is defined in the 'solutionsecret' solution.",
"items": {
"type": "object",
"properties": {
"envvarName": {
"type": "string",
"description": "The name of the environment variable",
"pattern": "^[A-Z_]{1,}[A-Z0-9_]{0,99}$"
},
"secretRef": {
"type": "string",
"description": "The reference to the 'solutionSecret' object and the key from it's 'secrets' field in the form `{solutionSecretName}/{solutionSecretSecretsKey}`",
"pattern": "^[^/]+/[^/]+$"
}
},
"required": [
"envvarName",
"secretRef"
]
},
"minItems": 1
},
"cspHeader": {
"type": "object",
"description": "Describes the properties of the CSP header returned in the responses. This configuration may not represent the final CSP header.",
"properties": {
"directives": {
"type": "array",
"description": "The list of CSP header directives.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The directive name.",
"minLength": 1,
"maxLength": 256
},
"parameters": {
"type": "array",
"description": "The parameters associated with the directive. For many directives, it's the source list. Some directives don't need parameters.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"maxItems": 256
}
},
"required": ["name"],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 256,
"additionalProperties": false
}
},
"required": ["directives"],
"additionalProperties": false
}
},
"required": [
"name",
"image"
]
}
}
Attributes
Note: The
secretEnvvarsattribute implements a feature that is not yet finalized and can change without notice.
| Name | Description |
|---|---|
name |
Required. The unique name of the function within the solution context. This will also be the name of the REST endpoint. This name must be unique across all the functions within this solution. Maximum length of 253 characters, alphanumeric only. |
image |
Required. The full path for the Docker image that you want Solution Services to deploy on the platform. This URL must be within a public Docker registry. |
envvars |
List of key-value pairs of environment variables to make accessible to the Docker image you specify in image. Docker images can access the following predefined environment variables by default, without any user action. • APPD_INTERNAL_EGRESS_HOST: Tenant internal egress hostname |
imagePullSecrets |
Names of image pull secrets to be added to the function's pod. |
resources |
Resource requests and limits for each pod or replica. This allows you to customize the resources of each replica (how much CPU, RAM). See Resource Management for Pods and Containers. For example, {"resources":{"requests":{"memory":"64Mi","cpu":"250m"},"limits":{"memory":"128Mi","cpu":"500m"}}} |
concurrency |
Soft, hard, and target limits on concurrency. Concurrency is how many requests the function can receive before the platform creates a new replica of it. Configuring concurrency and scaleBounds for your function improves its scalability.• A hard limit is an enforced upper bound. If concurrency reaches the hard limit, surplus requests are buffered and must wait until enough capacity is free to execute the requests. • A soft limit is an upper bound that only applies in some situations, such as a sudden burst of requests. • A target utilization value specifies what percentage of the previously specified target should actually be targeted by the autoscaler -- in other words, the hotness at which a replica can run at before the defined hard limit is reached. See Configuring Concurrency. |
scaleBounds |
Lower and upper scale bounds (number of pods to create for this function). Default: 0. Solution Services scales this function's pods to zero unless you configure this property to be 1 or greater. This means that, when this function isn't in use, there is no pod running for this function. New pods are created when needed, based on the load. For example, when you access your function through the external endpoint, a new temporary pod is created. However, if your function is set to scale-to-zero, it will take a significant time to get a response when sending a request if the current number of pods is 0. That's because it takes time to initialize a new pod. If this is an issue for you, set scaleBounds.lower to >= 1. |
secretEnvvars |
Deprecated. Environment variables whose values refer to secrets from ASMS Vault. You have to create the secrets in ASMS Vault first and then refer to them here. Solution Services will set the values of these environment variables based on the secrets from ASMS Vault. Important notes: 1. You must create secrets through the ASMS Vault UI. 2. You have to create secrets in the following base path: secret/appdynamics/bootstrap/zodiac/<your-solution-name>. You can use any relative path inside this base path. For example, if you create a secret in secret/appdynamics/bootstrap/zodiac/<your-solution-name>/a/b/c, this means that the secretEnvvars attribute in your function definition will have to have the path a/b/c. So, the secretEnvvars.path field refers to the relative path in- vault inside your unique solution base path.3. As the vault secrets are naturally key-value pairs, the environment variable value that your function has access to is the stringified version of a JSON object that contains those key-value pairs. 4. If, during the solution installation, your function refers to a secret which doesn't exist in the vault, the solution installation will fail. 5. If the secret is updated, your function's environment variable will not automatically update. Also, if you reinstall the solution, the environment variable value will not automatically update unless you change the environment variable name or path. Best practice is to use a versioning system for your secrets. For example, you can create a secret in secret/appdynamics/bootstrap/zodiac/mysol/my-secret/1.0.0, then secret/appdynamics/bootstrap/zodiac/mysol/my-secret/1.0.1. The versions of the solution in the manifest can be in sync with the versions in the vault paths. |
secretEnvvarsV2 |
Deprecated. List of environment variables whose values are references to values within a solutionsecret:solutionSecret object. Format: [{"envvarName": "<env-var-name-for-function-to-reference>", "secretRef": "<name-of-solutionSecret>/<name-of-env-var>"}, {"<another-reference>"}]See Examples. |
cspHeader |
Configures the Content-Security-Policy (CSP) HTTP response headers that this function returns in its response. You specify this configuration as an array of CSP directives named directives. Each item in the directives array is:• name: The directive name • parameters: Optional. The parameters associated with the directive. For many directives, it's the source list. Some directives don't need parameters. These CSP directives are already supplied by default. Your directives are merged with these defaults: {"name": "script-src", "parameters": ["'self'", "'unsafe-eval'", "'unsafe-inline'"]}, {"name": "object-src", "parameters": ["'self'"]} |
Examples
Simple definition that references a Docker image in a private repository:
{
"name": "my-func",
"image": "gcr.io/knative-samples/helloworld-go",
"imagePullSecrets": ["my-secret"]
}
A definition that passes some environment variables to a function, and specifies the minimum and maximum number of pods this function can scale up or down:
{
"name": "my-func",
"image": "gcr.io/knative-samples/helloworld-go",
"envvars": {
"OCO_CMD": "-p orion --path optimize --instance demo/demo",
"SCRIBE_DISABLE_FB": "1",
},
"scaleBounds": {
"lower": 1,
"upper": 10
}
}
A definition that passes some environment variables whose values refer to secrets from ASMS Vault to a function:
{
"name": "my-func",
"image": "gcr.io/knative-samples/helloworld-go",
"secretEnvvars": [
{
"name": "MY_VAR_1",
"path": "a"
},
{
"name": "MY_VAR_2",
"path": "b/c"
}
]
}
A definition that passes some environment variables whose values have been encrypted by SOPS:
{
"name": "my-func",
"image": "gcr.io/knative-samples/helloworld-go",
"secretEnvvarsV2": [
{
"envvarName": "MY_VAR_1",
"secretRef": "mySecretsObject/secret1"
},
{
"envvarName": "MY_VAR_2",
"secretRef": "mySecretsObject/secret2"
}
]
}
A definition that specifies CSP directives:
{
"name": "my-func",
"image": "gcr.io/knative-samples/helloworld-go",
"cspHeader": {
"directives": [
{
"name": "default-src",
"parameters": ["'self'", "example.com", "*.example.com", "example.org"]
},
{
"name": "upgrade-insecure-requests"
}
]
}
}