Skip to content

Commit

Permalink
fix: Target -> resource docs refactor
Browse files Browse the repository at this point in the history
  • Loading branch information
adityachoudhari26 committed Dec 9, 2024
1 parent 620e67d commit a014bcc
Show file tree
Hide file tree
Showing 20 changed files with 259 additions and 259 deletions.
20 changes: 10 additions & 10 deletions apps/docs/pages/core-concepts/deployments.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,12 @@ A deployment in Ctrlplane typically includes:
across different stages.

4. **Job Configurations**: Specifications for the jobs that will be created and
run for each release and target.
run for each release and resource.

5. **Variables**: Target-specific variables that allow the same pipeline to be
5. **Variables**: Resource-specific variables that allow the same pipeline to be
used across different environments.

## Systems, Environments, and Target Filtering
## Systems, Environments, and Resource Filtering

Ctrlplane uses a hierarchical structure to manage deployments:

Expand All @@ -57,12 +57,12 @@ Ctrlplane uses a hierarchical structure to manage deployments:
environment can be configured with specific settings and policies.

3. **Environment Configuration**: Each environment is configured with label
filters to determine which targets fall under that environment. This allows
filters to determine which resources fall under that environment. This allows
for fine-grained control over where deployments are applied.

4. **Target Filtering**: When a release is created, Ctrlplane uses the
environment's label filters to identify matching targets. It then runs the
appropriate jobs for each of these targets.
4. **Resource Filtering**: When a release is created, Ctrlplane uses the
environment's label filters to identify matching resources. It then runs the
appropriate jobs for each of these resources.

5. **Inter-Environment Policies**: Environments are connected by policies that
determine when and how jobs should run. These policies control the
Expand All @@ -77,14 +77,14 @@ Ctrlplane uses a hierarchical structure to manage deployments:

3. **Environment Processing**: For each environment in the system:

- The environment's label filters are applied to identify relevant targets.
- Jobs are created for each matching target based on the deployment's job
- The environment's label filters are applied to identify relevant resources.
- Jobs are created for each matching resource based on the deployment's job
definitions.

4. **Policy Enforcement**: Inter-environment policies determine when jobs can
run, allowing for controlled progression through environments.

5. **Job Execution**: Jobs are executed on the identified targets, applying the
5. **Job Execution**: Jobs are executed on the identified resources, applying the
release changes.

## Creating and Managing Deployments
Expand Down
32 changes: 16 additions & 16 deletions apps/docs/pages/core-concepts/deployments/releases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Remember, the actual building and packaging of your software should be handled
by your existing CI pipelines or build systems. Ctrlplane takes over from the
point where your software is built and ready for distribution, solving the
complex problem of managing deployments across a large and potentially diverse
set of targets.
set of resources.

## Key Characteristics of Releases

Expand All @@ -18,7 +18,7 @@ set of targets.

2. **Deployment Association**: Releases are created as part of a deployment in
Ctrlplane. They represent the content that will be deployed across various
environments and targets.
environments and resources.

3. **External Build Process**: Ctrlplane does not manage the build process for
releases. The actual compilation, packaging, or preparation of your software
Expand All @@ -41,7 +41,7 @@ set of targets.
## Release Dependencies

Since Ctrlplane is meant for solving the way releases are deployed across
targets, it's very common to have version dependencies on other deployments. In
resources, it's very common to have version dependencies on other deployments. In
the world of software, this could mean a microservice depends on a specific
version of another microservice to ensure it has the required APIs.

Expand All @@ -68,40 +68,40 @@ deployments. This feature allows you to:
When creating a release, you can define expresions to determine what version of
other deployments is required.

### Managing Dependencies with Target Metadata Grouping
### Managing Dependencies with Resource Metadata Grouping

In most cases, a target has multiple deployments associated with it, making it
easy to verify if a specific version is deployed on that target as required by
In most cases, a resource has multiple deployments associated with it, making it
easy to verify if a specific version is deployed on that resource as required by
another deployment. However, complexities arise when dependencies involve other
targets, where the deployment version might be present on any of these dependent
targets.
resources, where the deployment version might be present on any of these dependent
resources.

To address this, Ctrlplane uses target metadata grouping. This mechanism allows
you to logically group targets based on their metadata attributes. By doing so,
Ctrlplane can accurately determine which targets to inspect to verify if the
To address this, Ctrlplane uses resource metadata grouping. This mechanism allows
you to logically group resources based on their metadata attributes. By doing so,
Ctrlplane can accurately determine which resources to inspect to verify if the
software has been deployed.

The idea is to create logical associations between targets that share common
The idea is to create logical associations between resources that share common
characteristics, such as being part of the same kubernetes cluster. This is
particularly useful in complex infrastructures or distributed systems where
deployments span multiple infrastructure components.

For example:

1. **Single Cluster Deployment**: If you have a single Kubernetes namespace
represented by a target, you can easily check if a version is deployed on
that cluster without additional grouping if that target is used by all the
represented by a resource, you can easily check if a version is deployed on
that cluster without additional grouping if that resource is used by all the
deployments.

2. **Multiple Clusters Deployment**: If you have multiple Kubernetes namespaces,
you might need to group targets by cluster name. This way, Ctrlplane can
you might need to group resources by cluster name. This way, Ctrlplane can
check all namespaces within the specified cluster to determine if the
required version is deployed.

By defining metadata groups and associating deployments with these groups, you
ensure that version checks are performed within the relevant scope, maintaining
consistency and compatibility across your system.

When defining release dependencies, carefully consider how your targets are
When defining release dependencies, carefully consider how your resources are
grouped and which metadata attributes are most relevant for determining version
compatibility across your system.
12 changes: 6 additions & 6 deletions apps/docs/pages/core-concepts/deployments/variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,20 @@ environment-specific settings, secrets, and runtime values into your pipelines.

Ctrlplane offers three variable scopes:

1. **System Level**: Global variables applicable to all targets across all
1. **System Level**: Global variables applicable to all resources across all
deployments within a system.
2. **Deployment Level (Wildcard Selector)**: Variables applicable to all targets
2. **Deployment Level (Wildcard Selector)**: Variables applicable to all resources
within a specific deployment.
3. **Deployment Level (Custom Selector)**: Variables applicable to a subset of
targets within a deployment, based on defined selectors (e.g., metadata,
resources within a deployment, based on defined selectors (e.g., metadata,
environment, type).

## Precedence and Conflict Resolution

When variable keys are defined at multiple levels, Ctrlplane resolves conflicts
in this order:

1. Per-Target Variables (highest priority)
1. Per-Resource Variables (highest priority)
2. Deployment Level Variables
3. System Level Variables (lowest priority)

Expand All @@ -42,7 +42,7 @@ Variables can be used in:

- Workflow definitions: `{{ vars.api_key }}`
- Job agent configurations
- Target configurations
- Resource configurations

## Best Practices

Expand All @@ -56,7 +56,7 @@ Variables can be used in:
endpoints, common timeouts)
- Leverage deployment-level variables for environment-specific settings (e.g.,
staging vs. production configs)
- Utilize custom selectors for fine-grained control over specific target groups
- Utilize custom selectors for fine-grained control over specific resource groups
- Regularly audit and rotate sensitive variables, especially secrets

By mastering Ctrlplane's variable system, DevOps engineers can create flexible,
Expand Down
30 changes: 15 additions & 15 deletions apps/docs/pages/core-concepts/environments.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Environments

Environments in Ctrlplane are logical groupings of targets that represent
Environments in Ctrlplane are logical groupings of resources that represent
distinct stages in your software deployment pipeline. They are defined at the
system level and play a crucial role in organizing and managing the deployment
process across various infrastructure components.
Expand All @@ -22,27 +22,27 @@ of releases through predefined stages.
### Environment Policies

Environment policies determine how deployments move from one environment's
targets to the next. These policies can include:
resources to the next. These policies can include:

- Approval workflows
- Automated checks
- Rollback strategies
- Deployment windows

### Target Filters
### Resource Filters

Each environment uses target filters to dynamically determine which targets are
Each environment uses resource filters to dynamically determine which resources are
associated with it. This feature allows for flexible and automatic assignment of
targets to environments based on their characteristics.
resources to environments based on their characteristics.

## Dynamic Target Association
## Dynamic Resource Association

The use of target filters enables dynamic addition and removal of targets from
The use of resource filters enables dynamic addition and removal of resources from
environments. As a result:

1. Pipelines and deployments automatically run against newly added targets.
1. Pipelines and deployments automatically run against newly added resources.
2. New software releases or upgrades are automatically applied to relevant
targets.
resources.

This dynamic association ensures that your deployment process remains agile and
responsive to changes in your infrastructure.
Expand All @@ -58,7 +58,7 @@ allows for:
- Improved fault isolation

For example, you might have production environments like `prod-us-west`,
`prod-us-east`, `prod-eu-central`, each with its own set of targets and
`prod-us-east`, `prod-eu-central`, each with its own set of resources and
potentially different rollout schedules.

## Benefits of Using Environments
Expand All @@ -67,7 +67,7 @@ potentially different rollout schedules.
progression.
2. **Consistency**: Standardized environments across all deployments in a
system.
3. **Flexibility**: Dynamic target association allows for easy scaling and
3. **Flexibility**: Dynamic resource association allows for easy scaling and
infrastructure changes.
4. **Control**: Environment policies provide fine-grained control over the
deployment process.
Expand All @@ -83,7 +83,7 @@ A typical environment setup might include:
3. **Staging**: A pre-production environment mirroring production
4. **Production**: Multiple production environments for different regions

Each of these environments would have its own target filters and policies,
Each of these environments would have its own resource filters and policies,
ensuring that software progresses through the pipeline in a controlled and
consistent manner.

Expand All @@ -93,19 +93,19 @@ In Ctrlplane, environments are typically managed through the UI or API. The
environment configuration includes:

1. Name and description
2. Target filters
2. Resource filters
3. Associated policies
4. Any environment-specific variables or configurations

For example, creating an environment might involve setting up target filters
For example, creating an environment might involve setting up resource filters
like:

```yaml
environment: staging
region: us-west
```
This would automatically associate all targets with matching labels to the
This would automatically associate all resources with matching labels to the
staging environment in the US West region.
By leveraging environments effectively in Ctrlplane, you can create a robust,
Expand Down
6 changes: 3 additions & 3 deletions apps/docs/pages/core-concepts/jobs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ capabilities.
Jobs in Ctrlplane can be created by various events:

- New releases
- New targets added to an environment
- Changes in filtering labels of an environment or target
- New resources added to an environment
- Changes in filtering labels of an environment or resource
- Manual intervention
- Triggering of a runbook

Expand All @@ -47,7 +47,7 @@ real-time information, Ctrlplane offers several advantages:

1. **Centralized View:** Ctrlplane provides a unified interface to monitor jobs
across different CI/CD platforms.
2. **Advanced Orchestration:** Based on configured policies, targets, and
2. **Advanced Orchestration:** Based on configured policies, resources, and
environments, Ctrlplane can orchestrate complex deployment scenarios that may
involve multiple CI/CD systems.
3. **Automated Triggering:** Ctrlplane can automatically trigger jobs based on
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/pages/core-concepts/jobs/agents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The primary purposes of job agents in Ctrlplane are:
## How Job Agents Work

1. **Job Initiation:** When Ctrlplane determines a job needs to run (e.g., due
to a new release or target addition), it communicates with the appropriate
to a new release or resource addition), it communicates with the appropriate
job agent.
2. **External System Interaction:** The job agent then triggers the
corresponding job in the external CI/CD system using that system's API or
Expand Down
14 changes: 7 additions & 7 deletions apps/docs/pages/core-concepts/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ import Youtube from "react-youtube";
<Youtube videoId="72_6ZtDzmZo" />
</div>

**Targets** are entities such as Kubernetes clusters, virtual machines, or other
logical resources, that the system interacts with. These targets can be added
manually or through **Target Providers**, which automate the process by
continuously monitoring infrastructure, updating target statuses, and providing
real-time visibility. Targets are organized into **Environments**, which
dynamically update based on target filters, ensuring the right infrastructure is
**Resources** are entities such as Kubernetes clusters, virtual machines, or other
logical resources, that the system interacts with. These resources can be added
manually or through **Resource Providers**, which automate the process by
continuously monitoring infrastructure, updating resource statuses, and providing
real-time visibility. Resources are organized into **Environments**, which
dynamically update based on resource filters, ensuring the right infrastructure is
always in place for deployments.

Once targets and environments are established, **Deployments** come into play. A
Once resources and environments are established, **Deployments** come into play. A
deployment is the process of releasing a specific version of a system into an
environment. Each deployment is governed by **Environment Policies**, which
manage how software transitions between environments. When a release is created,
Expand Down
6 changes: 3 additions & 3 deletions apps/docs/pages/core-concepts/systems.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -97,9 +97,9 @@ How should I organize my deployments into systems?

Focus on these two crucial aspects:

1. **Deployment Targets:** Ensure that all deployments within a system share
identical deployment targets. This is crucial because deployment pipelines
are structured to perform deployments on a uniform set of targets within the
1. **Deployment Resources:** Ensure that all deployments within a system share
identical deployment resources. This is crucial because deployment pipelines
are structured to perform deployments on a uniform set of resources within the
system.
2. **Environments:** Ensure that all deployments within a system operate within
the same environments and adhere to the same environment policies.
Expand Down
Loading

0 comments on commit a014bcc

Please sign in to comment.