From 3feb781a67770b998a87189f29d07c92f9af1def Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 20 Jul 2024 22:39:49 -0400 Subject: [PATCH] Update docs for operator (#282) Co-authored-by: michaeljguarino --- pages/deployments/operator/api.md | 147 +++++++++++++++++++++++------- 1 file changed, 112 insertions(+), 35 deletions(-) diff --git a/pages/deployments/operator/api.md b/pages/deployments/operator/api.md index 162b7a9e..00049605 100644 --- a/pages/deployments/operator/api.md +++ b/pages/deployments/operator/api.md @@ -30,6 +30,7 @@ Package v1alpha1 contains API Schema definitions for the deployments v1alpha1 AP - [ScmConnection](#scmconnection) - [ServiceAccount](#serviceaccount) - [ServiceDeployment](#servicedeployment) +- [StackDefinition](#stackdefinition) @@ -344,8 +345,6 @@ _Appears in:_ | `clusterRestoreRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ClusterRestoreRef pointing to source ClusterRestore. | | Optional: {}
| - - #### ClusterSpec @@ -389,7 +388,6 @@ _Appears in:_ | --- | --- | --- | --- | | `tags` _object (keys:string, values:string)_ | Tags the cluster tags to target | | Optional: {}
| | `distro` _[ClusterDistro](#clusterdistro)_ | Distro kubernetes distribution to target | | Optional: {}
| -| `clusterRefs` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core) array_ | | | | #### CommandAttributes @@ -466,6 +464,25 @@ _Appears in:_ | `envFrom` _[EnvFrom](#envfrom) array_ | | | Optional: {}
| +#### CustomRunStep + + + + + + + +_Appears in:_ +- [StackDefinitionSpec](#stackdefinitionspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `args` _string array_ | Args allow you to provide any additional
args that should be passed to the custom
run step. | | Required: {}
| +| `cmd` _string_ | Cmd defines what command should be executed
as part of your custom run step. | | Required: {}
| +| `requireApproval` _boolean_ | RequireApproval controls whether this custom run step
will require an approval to proceed. | | Optional: {}
| +| `stage` _[StepStage](#stepstage)_ | Stage controls at which stage should this custom run
step be executed. | | Enum: [PLAN VERIFY APPLY INIT DESTROY]
Required: {}
| + + #### CustomStackRun @@ -768,23 +785,25 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | Name of this Stack. If not provided InfrastructureStack's own name from InfrastructureStack.ObjectMeta will be used. | | Optional: {}
| -| `type` _[StackType](#stacktype)_ | Type specifies the tool to use to apply it | | Enum: [TERRAFORM ANSIBLE]
| +| `type` _[StackType](#stacktype)_ | Type specifies the tool to use to apply it | | Enum: [TERRAFORM ANSIBLE CUSTOM]
Required: {}
| | `repositoryRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | RepositoryRef to source IaC from | | Required: {}
| | `clusterRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | | | Required: {}
| | `projectRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ProjectRef references project this stack belongs to.
If not provided, it will use the default project. | | Optional: {}
| | `git` _[GitRef](#gitref)_ | Git reference w/in the repository where the IaC lives | | | -| `manageState` _boolean_ | Whether you want Plural to manage the state of this stack | | Optional: {}
| -| `workdir` _string_ | The working directory within the git spec you want to run commands in (useful for projects with external modules) | | Optional: {}
| +| `manageState` _boolean_ | ManageState - whether you want Plural to manage the state of this stack | | Optional: {}
| +| `workdir` _string_ | Workdir - the working directory within the git spec you want to run commands in (useful for projects with external modules) | | Optional: {}
| | `jobSpec` _[JobSpec](#jobspec)_ | JobSpec optional k8s job configuration for the job that will apply this stack | | Optional: {}
| -| `configuration` _[StackConfiguration](#stackconfiguration)_ | Configuration version/image config for the tool you're using | | | +| `configuration` _[StackConfiguration](#stackconfiguration)_ | Configuration version/image config for the tool you're using | | Required: {}
| | `cron` _[StackCron](#stackcron)_ | Configuration for cron generation of stack runs | | Optional: {}
| | `approval` _boolean_ | Approval whether to require approval | | Optional: {}
| | `bindings` _[Bindings](#bindings)_ | Bindings contain read and write policies of this cluster | | Optional: {}
| | `environment` _[StackEnvironment](#stackenvironment) array_ | | | Optional: {}
| | `files` _[StackFile](#stackfile) array_ | Files reference to Secret with a key as a part of mount path and value as a content | | Optional: {}
| -| `detach` _boolean_ | If true, detach the stack on CR deletion, leaving all cloud resources in-place. | | Optional: {}
| -| `actor` _string_ | User email to use for default Plural authentication in this stack. | | Optional: {}
| +| `detach` _boolean_ | Detach if true, detach the stack on CR deletion, leaving all cloud resources in-place. | | Optional: {}
| +| `actor` _string_ | Actor - user email to use for default Plural authentication in this stack. | | Optional: {}
| | `scmConnectionRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | | | Optional: {}
| +| `stackDefinitionRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | | | Optional: {}
| +| `tags` _object (keys:string, values:string)_ | Tags used to filter stacks. | | Optional: {}
| #### JobSpec @@ -1222,8 +1241,25 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `git` _[GitRef](#gitref)_ | Git ... | | Optional: {}
| -| `templates` _[PrAutomationTemplate](#prautomationtemplate) array_ | Templates ... | | Optional: {}
| +| `git` _[GitRef](#gitref)_ | Git Location to source external files from | | Optional: {}
| +| `templates` _[PrAutomationTemplate](#prautomationtemplate) array_ | Template files to use to generate file content | | Optional: {}
| + + +#### PrAutomationDeleteConfiguration + + + + + + + +_Appears in:_ +- [PrAutomationSpec](#prautomationspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `files` _string array_ | Individual files to delete | | Optional: {}
| +| `folders` _string array_ | Entire folders to delete | | Optional: {}
| #### PrAutomationSpec @@ -1244,17 +1280,18 @@ _Appears in:_ | `branch` _string_ | The base branch this pr will be based on (defaults to the repo's main branch) | | Optional: {}
| | `documentation` _string_ | Documentation ... | | Optional: {}
| | `identifier` _string_ | Identifier is a string referencing the repository, i.e. for GitHub it would be "/" | | Optional: {}
| -| `message` _string_ | Message ... | | Optional: {}
| -| `name` _string_ | Name ... | | Optional: {}
| -| `title` _string_ | Title... | | Optional: {}
| -| `clusterRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ClusterRef ... | | Optional: {}
| -| `scmConnectionRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ScmConnectionRef ... | | Required: {}
| +| `message` _string_ | Message the commit message this pr will incorporate | | Optional: {}
| +| `name` _string_ | Name name of the automation in the console api (defaults to metadata.name) | | Optional: {}
| +| `title` _string_ | Title the title of the generated pr | | Optional: {}
| +| `clusterRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ClusterRef a cluster this pr works on | | Optional: {}
| +| `scmConnectionRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ScmConnectionRef the SCM connection to use for generating this PR | | Required: {}
| | `repositoryRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | RepositoryRef ... | | Optional: {}
| -| `serviceRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ServiceRef ... | | Optional: {}
| +| `serviceRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectreference-v1-core)_ | ServiceRef the service this PR acts on | | Optional: {}
| | `bindings` _[PrAutomationBindings](#prautomationbindings)_ | Bindings contain read and write policies of pr automation | | Optional: {}
| -| `configuration` _[PrAutomationConfiguration](#prautomationconfiguration) array_ | Configuration ... | | Optional: {}
| -| `creates` _[PrAutomationCreateConfiguration](#prautomationcreateconfiguration)_ | Creates ... | | Optional: {}
| -| `updates` _[PrAutomationUpdateConfiguration](#prautomationupdateconfiguration)_ | Updates ... | | Optional: {}
| +| `configuration` _[PrAutomationConfiguration](#prautomationconfiguration) array_ | Configuration self-service configuration for the UI wizard generating this PR | | Optional: {}
| +| `creates` _[PrAutomationCreateConfiguration](#prautomationcreateconfiguration)_ | Specs for files to be templated and created | | Optional: {}
| +| `updates` _[PrAutomationUpdateConfiguration](#prautomationupdateconfiguration)_ | Spec for files to be updated, using regex replacement | | Optional: {}
| +| `deletes` _[PrAutomationDeleteConfiguration](#prautomationdeleteconfiguration)_ | Spec for files and folders to be deleted | | Optional: {}
| #### PrAutomationTemplate @@ -1270,9 +1307,9 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `destination` _string_ | Destination ... | | Required: {}
| -| `external` _boolean_ | External ... | | Required: {}
| -| `source` _string_ | Source ... | | Optional: {}
| +| `destination` _string_ | The destination to write the file to | | Required: {}
| +| `external` _boolean_ | Whether it is being sourced from an external git repository | | Required: {}
| +| `source` _string_ | The source file to use for templating | | Optional: {}
| #### PrAutomationTrigger @@ -1323,12 +1360,12 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `files` _string array_ | Files ... | | Optional: {}
| -| `matchStrategy` _[MatchStrategy](#matchstrategy)_ | MatchStrategy ... | | Optional: {}
| -| `regexReplacements` _[RegexReplacement](#regexreplacement) array_ | RegexReplacements ... | | Optional: {}
| -| `regexes` _string array_ | Regexes ... | | Optional: {}
| -| `replaceTemplate` _string_ | ReplaceTemplate ... | | Optional: {}
| -| `yq` _string_ | Yq ... | | Optional: {}
| +| `files` _string array_ | Files to update | | Optional: {}
| +| `matchStrategy` _[MatchStrategy](#matchstrategy)_ | MatchStrategy, see enum for behavior | | Optional: {}
| +| `regexReplacements` _[RegexReplacement](#regexreplacement) array_ | Full regex + replacement structs in case there is different behavior per regex | | Optional: {}
| +| `regexes` _string array_ | The regexes to apply on each file | | Optional: {}
| +| `replaceTemplate` _string_ | The template to use when replacing a regex | | Optional: {}
| +| `yq` _string_ | (Unused so far) | | Optional: {}
| #### Project @@ -1419,7 +1456,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `regex` _string_ | Regex ... | | Required: {}
| +| `regex` _string_ | The regex to match a substring on | | Required: {}
| | `file` _string_ | The file this replacement will work on | | Required: {}
| | `replacement` _string_ | Replacement to be substituted for the match in the regex | | Required: {}
| | `templated` _boolean_ | Whether you want to apply templating to the regex before compiling | | Optional: {}
| @@ -1476,7 +1513,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | Name is a human-readable name of the ScmConnection. | | Required: {}
| -| `type` _[ScmType](#scmtype)_ | Type is the name of the scm service for the ScmConnection.
One of (ScmType): [github, gitlab] | | Enum: [GITHUB GITLAB]
Required: {}
Type: string
| +| `type` _[ScmType](#scmtype)_ | Type is the name of the scm service for the ScmConnection.
One of (ScmType): [github, gitlab] | | Enum: [GITHUB GITLAB BITBUCKET]
Required: {}
Type: string
| | `tokenSecretRef` _[SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#secretreference-v1-core)_ | Token ... | | Optional: {}
| | `username` _string_ | Username ... | | Optional: {}
| | `baseUrl` _string_ | BaseUrl is a base URL for Git clones for self-hosted versions. | | Optional: {}
| @@ -1773,12 +1810,14 @@ _Appears in:_ _Appears in:_ - [InfrastructureStackSpec](#infrastructurestackspec) +- [StackDefinitionSpec](#stackdefinitionspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `image` _string_ | Image optional custom image you might want to use | | Optional: {}
| -| `version` _string_ | Version the semver of the tool you wish to use | | | +| `version` _string_ | Version the semver of the tool you wish to use | | Required: {}
| | `hooks` _[StackHook](#stackhook) array_ | Hooks to run at various stages of the stack run | | Optional: {}
| +| `tag` _string_ | Tag is the docker image tag you wish to use
if you're customizing the version | | Optional: {}
| #### StackCron @@ -1798,6 +1837,43 @@ _Appears in:_ | `autoApprove` _boolean_ | Whether to automatically approve cron-spawned runs | | Optional: {}
| +#### StackDefinition + + + +StackDefinition is the Schema for the StackDefinitions API + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `deployments.plural.sh/v1alpha1` | | | +| `kind` _string_ | `StackDefinition` | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[StackDefinitionSpec](#stackdefinitionspec)_ | | | | + + +#### StackDefinitionSpec + + + +StackDefinitionSpec defines the desired state of StackDefinition + + + +_Appears in:_ +- [StackDefinition](#stackdefinition) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name of this StackDefinition. If not provided StackDefinition's own name
from StackDefinition.ObjectMeta will be used. | | Optional: {}
| +| `description` _string_ | Description can be used to describe this StackDefinition. | | Optional: {}
| +| `steps` _[CustomRunStep](#customrunstep) array_ | Steps is a list of custom run steps that will be executed as
part of the stack run. | | Optional: {}
| +| `configuration` _[StackConfiguration](#stackconfiguration)_ | Configuration allows modifying the StackDefinition environment
and execution. | | Required: {}
| + + #### StackEnvironment @@ -1811,7 +1887,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `name` _string_ | | | | +| `name` _string_ | | | Required: {}
| | `value` _string_ | | | Optional: {}
| | `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#secretkeyselector-v1-core)_ | | | Optional: {}
| | `configMapRef` _[ConfigMapKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#configmapkeyselector-v1-core)_ | | | Optional: {}
| @@ -1847,9 +1923,9 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `cmd` _string_ | the command this hook will execute | | | +| `cmd` _string_ | the command this hook will execute | | Required: {}
| | `args` _string array_ | optional arguments to pass to the command | | Optional: {}
| -| `afterStage` _[StepStage](#stepstage)_ | | | Enum: [INIT PLAN VERIFY APPLY]
| +| `afterStage` _[StepStage](#stepstage)_ | | | Enum: [INIT PLAN VERIFY APPLY DESTROY]
Required: {}
| #### StackSettings @@ -1904,6 +1980,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `createNamespace` _boolean_ | | | Optional: {}
| +| `enforceNamespace` _boolean_ | | | Optional: {}
| | `labels` _object (keys:string, values:string)_ | | | Optional: {}
| | `annotations` _object (keys:string, values:string)_ | | | Optional: {}
|