From 3ec062cf0cd94a116c2b0024e6f8f6bd406215dd Mon Sep 17 00:00:00 2001 From: Justin Brooks Date: Tue, 27 Aug 2024 16:43:52 -0400 Subject: [PATCH] clean up docs --- apps/docs/pages/_meta.json | 5 +- apps/docs/pages/deployments.mdx | 8 ++ apps/docs/pages/examples/deploy-to-gke.mdx | 1 + apps/docs/pages/github/actions-dispatcher.mdx | 36 ++++++++ .../pages/google-cloud/compute-scanner.mdx | 26 +++++- apps/docs/pages/job-executions/_meta.json | 4 - .../job-executions/integrations/_meta.json | 11 --- .../integrations/azure-devops.mdx | 1 - .../job-executions/integrations/circle-ci.mdx | 1 - .../job-executions/integrations/github.mdx | 82 ------------------- .../integrations/google-workflows.mdx | 9 -- .../job-executions/integrations/jenkins.mdx | 0 .../integrations/kubernetes-jobs.mdx | 13 --- .../introduction.mdx => jobs.mdx} | 0 apps/docs/pages/kubernetes/jobs-agent.mdx | 13 +++ .../{targets/introduction.mdx => targets.mdx} | 0 apps/docs/pages/targets/_meta.json | 1 - apps/docs/pages/targets/schemas/_meta.json | 4 +- .../docs/pages/targets/schemas/kubernetes.mdx | 42 +++++++++- .../pages/targets/target-providers/_meta.json | 5 -- .../pages/targets/target-providers/aws.mdx | 5 -- .../pages/targets/target-providers/azure.mdx | 3 - .../pages/targets/target-providers/google.mdx | 3 - .../targets/target-providers/terraform.mdx | 1 - .../validators/src/targets/kubernetes-v1.ts | 1 + 25 files changed, 125 insertions(+), 150 deletions(-) create mode 100644 apps/docs/pages/examples/deploy-to-gke.mdx delete mode 100644 apps/docs/pages/job-executions/_meta.json delete mode 100644 apps/docs/pages/job-executions/integrations/_meta.json delete mode 100644 apps/docs/pages/job-executions/integrations/azure-devops.mdx delete mode 100644 apps/docs/pages/job-executions/integrations/circle-ci.mdx delete mode 100644 apps/docs/pages/job-executions/integrations/github.mdx delete mode 100644 apps/docs/pages/job-executions/integrations/google-workflows.mdx delete mode 100644 apps/docs/pages/job-executions/integrations/jenkins.mdx delete mode 100644 apps/docs/pages/job-executions/integrations/kubernetes-jobs.mdx rename apps/docs/pages/{job-executions/introduction.mdx => jobs.mdx} (100%) create mode 100644 apps/docs/pages/kubernetes/jobs-agent.mdx rename apps/docs/pages/{targets/introduction.mdx => targets.mdx} (100%) delete mode 100644 apps/docs/pages/targets/target-providers/_meta.json delete mode 100644 apps/docs/pages/targets/target-providers/aws.mdx delete mode 100644 apps/docs/pages/targets/target-providers/azure.mdx delete mode 100644 apps/docs/pages/targets/target-providers/google.mdx delete mode 100644 apps/docs/pages/targets/target-providers/terraform.mdx diff --git a/apps/docs/pages/_meta.json b/apps/docs/pages/_meta.json index 955c682a..70e8e876 100644 --- a/apps/docs/pages/_meta.json +++ b/apps/docs/pages/_meta.json @@ -11,7 +11,7 @@ "systems": "Systems", "environments": "Environments", "targets": "Targets", - "workflows": "Workflow (CI)", + "jobs": "Jobs", "variables": "Variables", "runbooks": "Runbooks", "advanced": "Advanced", @@ -22,5 +22,6 @@ "title": "Integrations" }, "github": "GitHub", - "google-cloud": "Google Cloud" + "google-cloud": "Google Cloud", + "kubernetes": "Kubernetes" } diff --git a/apps/docs/pages/deployments.mdx b/apps/docs/pages/deployments.mdx index 16079e0d..8aa88401 100644 --- a/apps/docs/pages/deployments.mdx +++ b/apps/docs/pages/deployments.mdx @@ -40,6 +40,14 @@ The typical deployment process in Ctrlplane involves the following steps: deployment, providing you with visibility into the progress and success of your releases. +import { Callout } from "nextra/components"; + + + Its common to have multiple targets a single application may deploy too. It is + best practice to have a single deployment with a pipeline that supports + deploying to these different systems. + + ## Benefits of Deployments in Ctrlplane - **Automation:** Automates the entire deployment process, reducing manual diff --git a/apps/docs/pages/examples/deploy-to-gke.mdx b/apps/docs/pages/examples/deploy-to-gke.mdx new file mode 100644 index 00000000..48b21df1 --- /dev/null +++ b/apps/docs/pages/examples/deploy-to-gke.mdx @@ -0,0 +1 @@ +# Provisiong and deploying to GKE diff --git a/apps/docs/pages/github/actions-dispatcher.mdx b/apps/docs/pages/github/actions-dispatcher.mdx index 494b0135..c24d7980 100644 --- a/apps/docs/pages/github/actions-dispatcher.mdx +++ b/apps/docs/pages/github/actions-dispatcher.mdx @@ -4,3 +4,39 @@ GitHub Actions Dispatcher is allows you to trigger other GitHub Actions workflows from a single workflow. This is useful when you want to run multiple workflows in parallel or when you want to trigger a workflow from another repository. + +## Creating Actions + + + Due to [limitations of the GitHub + API](https://github.com/orgs/community/discussions/9752), workflows do not + return the run ID. Inorder for Ctrl Plane to get the ID it generates a random + one that is passed into the pipeline and is expected to be added to the Run + name. This can be done by adding + +```yaml +name: Receiving Workflow +run-name: Receiving Workflow [${{ inputs.distinct_id && inputs.distinct_id || 'N/A' }}] + +on: + workflow_dispatch: + inputs: + distinct_id: + description: "Distinct ID" + required: false +``` + + + +### Configuring a workflows + +Each provider will make there own assmputions about how values and properties +are expected to be passed to the underlying workflow. In this section we will +outline the format inwhich data will be passed in. + +First, the workflow must be able to be triggered by a dispatch. + +```yaml +on: + workflow_dispatch: {} +``` diff --git a/apps/docs/pages/google-cloud/compute-scanner.mdx b/apps/docs/pages/google-cloud/compute-scanner.mdx index 44e3d97c..b0b2e4ae 100644 --- a/apps/docs/pages/google-cloud/compute-scanner.mdx +++ b/apps/docs/pages/google-cloud/compute-scanner.mdx @@ -3,10 +3,28 @@ The Compute Scanner is a tool that scans Google Cloud projects for new instances and creates them for related deployments automatically. -Ctrlplane offers a managed and unmanaged version of the Compute Scanner. +Currently the compute scanner supports importing the following resources: + +- Google Kubernetes Engine Clusters (GKE) ## Managed Compute Scanner -The managed Compute Scanner is a service that is hosted -and managed by Ctrlplane. When adding a target provider you -will se an option to enable the managed Compute Scanner. +The managed Compute Scanner is build into the Ctrlplane solution. Each workspace +will is assigned a google service account. You need to invite this service +account to your projects you would like it to scan. Then in the UI, you can add +a new provider, select the managed install and add all the projects you will +like it to scale. Once you hit submit you may need to wait a few mins while it +scanns and imports all compute resources. + +## Unmanaged Compute Scanner + +The unmanaged Compute Scanner is a standalone tool that can be run in your +infrastrcuture. Similar to the managed solution, it imports all compute +resources from your projects. The unmanaged scanner is a docker container that +can be run in your infrastructure. You will need to provide the service account +credentials to the container. + +You may want to use the unmanaged solution when you want fine control over the scanner. + +| Environment Variable | Description | Required | Default | +| :------------------- | :---------- | -------- | ------- | diff --git a/apps/docs/pages/job-executions/_meta.json b/apps/docs/pages/job-executions/_meta.json deleted file mode 100644 index 4a1f25df..00000000 --- a/apps/docs/pages/job-executions/_meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "introduction": "Introduction", - "integrations": "Integrations" -} diff --git a/apps/docs/pages/job-executions/integrations/_meta.json b/apps/docs/pages/job-executions/integrations/_meta.json deleted file mode 100644 index 12d8b531..00000000 --- a/apps/docs/pages/job-executions/integrations/_meta.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "github": "GitHub Actions", - "gitlab": "GitLab", - "jenkins": "Jenkins", - "circle-ci": "Circle CI", - "team-city": "JetBrains TeamCity", - "azure-devops": "Azure DevOps", - "buildkite": "BuildKite", - "google-workflows": "Google Workflows", - "custom": "Custom Provider" -} diff --git a/apps/docs/pages/job-executions/integrations/azure-devops.mdx b/apps/docs/pages/job-executions/integrations/azure-devops.mdx deleted file mode 100644 index 285352d0..00000000 --- a/apps/docs/pages/job-executions/integrations/azure-devops.mdx +++ /dev/null @@ -1 +0,0 @@ -# Azure DevOps diff --git a/apps/docs/pages/job-executions/integrations/circle-ci.mdx b/apps/docs/pages/job-executions/integrations/circle-ci.mdx deleted file mode 100644 index 042cb548..00000000 --- a/apps/docs/pages/job-executions/integrations/circle-ci.mdx +++ /dev/null @@ -1 +0,0 @@ -# Circle CI diff --git a/apps/docs/pages/job-executions/integrations/github.mdx b/apps/docs/pages/job-executions/integrations/github.mdx deleted file mode 100644 index 9619eb58..00000000 --- a/apps/docs/pages/job-executions/integrations/github.mdx +++ /dev/null @@ -1,82 +0,0 @@ -import { Callout } from "nextra/components"; - -# GitHub Actions - -The GitHub Actions Job Agent in Ctrlplane enables seamless integration with -your GitHub Actions workflows. It allows you to trigger your GitHub Actions -pipelines directly from Ctrlplane, based on events like new releases, the -addition of new targets, or updates to existing targets. This -powerful integration lets you leverage Ctrlplane's flexible management -capabilities while utilizing the familiar and robust automation of GitHub -Actions. - -## Key Features - -- **Workflow Dispatch:** Triggers GitHub Actions workflows using the - workflow_dispatch event. -- **Input Parameters:** Pass custom input parameters to your GitHub Actions - workflows, allowing for dynamic customization. -- **Secure Authentication:** Uses GitHub personal access tokens (PATs) or GitHub - Bot for secure authentication with your GitHub repositories. - -## Configuration - - - Due to [limitations of the GitHub - API](https://github.com/orgs/community/discussions/9752), workflows do not - return the run ID. Inorder for Ctrl Plane to get the ID it generates a random - one that is passed into the pipeline and is expected to be added to the Run - name. This can be done by adding - -```yaml -name: Receiving Workflow -run-name: Receiving Workflow [${{ inputs.distinct_id && inputs.distinct_id || 'N/A' }}] - -on: - workflow_dispatch: - inputs: - distinct_id: - description: "Distinct ID" - required: false -``` - - - -### Configuring a workflows - -Each provider will make there own assmputions about how values and properties -are expected to be passed to the underlying workflow. In this section we will -outline the format inwhich data will be passed in. - -First, the workflow must be able to be triggered by a dispatch. - -```yaml -on: - workflow_dispatch: {} -``` - -Second, the following are the passed into the workflow in JSON. - -```yaml -on: - workflow_dispatch: - inputs: - distinct_id: - description: "Distinct ID" - required: false - environment: - description: "Environment" - required: true - release: - description: "Release" - required: true -``` - -### GitHub Bot - -Using the GitHub bot is the recommended apporach to configuring access to your -GitHub organization. - -### GitHub Token - -This apporach requires using an API token for the provider to trigger workflows. diff --git a/apps/docs/pages/job-executions/integrations/google-workflows.mdx b/apps/docs/pages/job-executions/integrations/google-workflows.mdx deleted file mode 100644 index f6363857..00000000 --- a/apps/docs/pages/job-executions/integrations/google-workflows.mdx +++ /dev/null @@ -1,9 +0,0 @@ -# Google Workflows - -The Google Cloud Workflows Job Agent in Ctrlplane integrates seamlessly with -Google Cloud Workflows, Google's serverless orchestration service. It empowers -you to trigger your Google Cloud Workflows directly from Ctrlplane, responding -to events such as new software releases, new target discoveries, or -updates to existing targets. This integration combines the flexibility and -management capabilities of Ctrlplane with the power and scalability of Google -Cloud Workflows. diff --git a/apps/docs/pages/job-executions/integrations/jenkins.mdx b/apps/docs/pages/job-executions/integrations/jenkins.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/apps/docs/pages/job-executions/integrations/kubernetes-jobs.mdx b/apps/docs/pages/job-executions/integrations/kubernetes-jobs.mdx deleted file mode 100644 index 10e10499..00000000 --- a/apps/docs/pages/job-executions/integrations/kubernetes-jobs.mdx +++ /dev/null @@ -1,13 +0,0 @@ -# Kubernetes Job - -The Kubernetes Job Agent in Ctrlplane seamlessly integrates with your -Kubernetes clusters, enabling you to trigger Kubernetes Jobs directly from -within Ctrlplane. It responds to events like new software releases, new -target discoveries, or updates to existing targets. This powerful -integration allows you to leverage Ctrlplane's flexible management capabilities -while harnessing the robust job execution capabilities of Kubernetes. - -- **Job Creation:** Dynamically creates Kubernetes Jobs based on predefined - templates or specifications. -- **Handlebars for Templating:** Utilizes Handlebars templating to dynamically - generate Kubernetes Job manifests. diff --git a/apps/docs/pages/job-executions/introduction.mdx b/apps/docs/pages/jobs.mdx similarity index 100% rename from apps/docs/pages/job-executions/introduction.mdx rename to apps/docs/pages/jobs.mdx diff --git a/apps/docs/pages/kubernetes/jobs-agent.mdx b/apps/docs/pages/kubernetes/jobs-agent.mdx new file mode 100644 index 00000000..74262551 --- /dev/null +++ b/apps/docs/pages/kubernetes/jobs-agent.mdx @@ -0,0 +1,13 @@ +# Jobs Agent + +The Kubernetes Job Agent seamlessly integrates with your Kubernetes clusters, +enabling you to trigger Kubernetes Jobs directly from within Ctrlplane. It +responds to events like new software releases, new target discoveries, or +updates to existing targets. This powerful integration allows you to leverage +Ctrlplane's flexible management capabilities while harnessing the robust job +execution capabilities of Kubernetes. + +- **Job Creation:** Dynamically creates Kubernetes Jobs based on predefined + templates or specifications. +- **Handlebars for Templating:** Utilizes Handlebars templating to dynamically + generate Kubernetes Job manifests. diff --git a/apps/docs/pages/targets/introduction.mdx b/apps/docs/pages/targets.mdx similarity index 100% rename from apps/docs/pages/targets/introduction.mdx rename to apps/docs/pages/targets.mdx diff --git a/apps/docs/pages/targets/_meta.json b/apps/docs/pages/targets/_meta.json index 50871c68..7f25ba6d 100644 --- a/apps/docs/pages/targets/_meta.json +++ b/apps/docs/pages/targets/_meta.json @@ -1,5 +1,4 @@ { - "introduction": "Introduction", "labels": "Labels", "target-providers": "Target Providers", "schemas": "Schemas" diff --git a/apps/docs/pages/targets/schemas/_meta.json b/apps/docs/pages/targets/schemas/_meta.json index 0967ef42..60387d9c 100644 --- a/apps/docs/pages/targets/schemas/_meta.json +++ b/apps/docs/pages/targets/schemas/_meta.json @@ -1 +1,3 @@ -{} +{ + "kubernetes": "kubernetes/v1" +} diff --git a/apps/docs/pages/targets/schemas/kubernetes.mdx b/apps/docs/pages/targets/schemas/kubernetes.mdx index 23ee4972..c1f773f1 100644 --- a/apps/docs/pages/targets/schemas/kubernetes.mdx +++ b/apps/docs/pages/targets/schemas/kubernetes.mdx @@ -1,7 +1,41 @@ -# Kubernetes +# `kubernetes/v1` -## `kubernetes/v1` Schemas +## ClusterAPI -### KubernetesAPI +```yaml +version: kubernetes/v1 +kind: ClusterAPI +config: + name: string + server: + certificateAuthorityData: string + endpoint: url +labels: + kubernetes/version: string + kubernetes/distribution: string + kubernetes/master-version: string + kubernetes/master-version-major: string + kubernetes/master-version-minor: string + kubernetes/master-version-patch: string +``` -### KubernetesNmamespace +## Namespace + +```yaml +version: kubernetes/v1 +kind: Namespace +config: + name: string + namespace: string + server: + certificateAuthorityData: string + endpoint: url +labels: + kubernetes/namespace: string + kubernetes/version: string + kubernetes/distribution: string + kubernetes/master-version: string + kubernetes/master-version-major: string + kubernetes/master-version-minor: string + kubernetes/master-version-patch: string +``` diff --git a/apps/docs/pages/targets/target-providers/_meta.json b/apps/docs/pages/targets/target-providers/_meta.json deleted file mode 100644 index 4d33194b..00000000 --- a/apps/docs/pages/targets/target-providers/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "aws": "AWS", - "azure": "Azure", - "google": "Google Cloud" -} diff --git a/apps/docs/pages/targets/target-providers/aws.mdx b/apps/docs/pages/targets/target-providers/aws.mdx deleted file mode 100644 index 8f661bcc..00000000 --- a/apps/docs/pages/targets/target-providers/aws.mdx +++ /dev/null @@ -1,5 +0,0 @@ -# Amazon Web Services (AWS) Target Provider - -## EKS - -## EC2 diff --git a/apps/docs/pages/targets/target-providers/azure.mdx b/apps/docs/pages/targets/target-providers/azure.mdx deleted file mode 100644 index c74b690b..00000000 --- a/apps/docs/pages/targets/target-providers/azure.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Azure - -## AKS diff --git a/apps/docs/pages/targets/target-providers/google.mdx b/apps/docs/pages/targets/target-providers/google.mdx deleted file mode 100644 index 06eb0266..00000000 --- a/apps/docs/pages/targets/target-providers/google.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Google Target Provider - -## GKE diff --git a/apps/docs/pages/targets/target-providers/terraform.mdx b/apps/docs/pages/targets/target-providers/terraform.mdx deleted file mode 100644 index b6f4d7e8..00000000 --- a/apps/docs/pages/targets/target-providers/terraform.mdx +++ /dev/null @@ -1 +0,0 @@ -# Terraform Target Provider diff --git a/packages/validators/src/targets/kubernetes-v1.ts b/packages/validators/src/targets/kubernetes-v1.ts index 0ec819a0..dcfa67bc 100644 --- a/packages/validators/src/targets/kubernetes-v1.ts +++ b/packages/validators/src/targets/kubernetes-v1.ts @@ -7,6 +7,7 @@ const clusterConfig = z.object({ endpoint: z.string().url(), }), }); + export const kubernetesClusterApiV1 = z.object({ version: z.literal("kubernetes/v1"), kind: z.literal("ClusterAPI"),