This is the multi-page printable view of this section. Click here to print.
Synchronization
- 1: Introduction
- 2: Bucket to Kubernetes
- 2.1: Introduction
- 2.2: Configuration
- 2.3: Observability
- 2.4: API Reference
- 3: Kubernetes to Bucket
- 3.1: Introduction
- 3.2: Configuration
- 3.3: Observability
- 3.4: API Reference
- 4: Kubernetes to Kubernetes
- 4.1: Introduction
- 4.2: Configuration
- 4.3: Observability
- 4.4: API Reference
- 5: Zookeeper to Zookeeper
- 5.1: Introduction
- 5.2: Configuration
- 5.3: API Reference
1 - Introduction
Synchronization is a critical process that enables the replication of data and configurations across different platform assets. This ensures consistency, integrity and improve the platform resiliency.
Key concepts
Source and destination
Each synchronization has at least two assets:
- Source: the original location or system from which data and configurations are retrived.
- Destination: the destination location or system where data and configurations are applied or updated.
Synchronization periodicity
There are three distinct types of synchronization processes designed to meet different operational needs: Synchronization, SynchronizationPlan, and LiveSynchronization.
Synchronization
The Synchronization process is designed to run once, making it ideal for one-time data alignment tasks or initial setup processes. This type of synchronization is useful when a system or component needs to be brought up-to-date with the latest data and configurations from another source without ongoing updates.
The synchronization process follows these rules:
- Object exists in Source: If a matching object exists in the source asset, it will be synchronized to the destination asset.
- Object only in Destination: If a matching object exists only in the destination asset, it will be removed from the destination asset.
SynchronizationPlan
The SynchronizationPlan process operates similarly to a cron job, allowing synchronization tasks to be scheduled at regular intervals. This type is ideal for systems that require periodic updates to ensure data and configuration consistency over time without the need for real-time accuracy.
LiveSynchronization
LiveSynchronization provides real-time synchronization, continuously monitoring and updating data and configurations as changes occur. This type of synchronization is essential for environments where immediate consistency and up-to-date information are crucial.
The synchronization process follows these rules:
- Object Creation/Update in Source: If a matching object is created or updated in the source asset, it will be synchronized to the destination asset.
- Object Deletion in Source: If a matching object is deleted in the source asset, the corresponding object will be deleted in the destination asset.
- Object Creation/Update in Destination: If a matching object is created or updated in the destination asset, it will be synchronized from the source asset.
- Object Deletion in Source: If a matching object is deleted in the source asset, the corresponding object will be deleted in the destination asset.
- Object Only in Destination: If a matching object exists only in the destination asset, it will be removed from the destination asset.
Resume
| Periodicity | Description |
|---|---|
| Synchronization | Synchronize data and configurations only once. |
| SynchronizationPlan | Synchronize data and configurations based on a scheduled period. |
| LiveSynchronization | Real-time synchronization of data and configurations. |
Prerequisites
Before initiating the Synchronization process, ensure the following prerequisites are met:
- Both source and destiation systems have been defined as Asset.
- There is a network connectivity between the assets and the operator.
2 - Bucket to Kubernetes
2.1 - Introduction
Bucket files can be synchronized in a Kubernetes cluster as Kubernetes objects using the bucket-to-kubernetes plugin.
Synchronization process
Special rules
There are no special rules for this synchronization plugin.
Blacklisted objects
There are some Kubernetes objects that are blacklisted by default and will be ignored by the synchronization process.
This is the list of the blacklisted objects:
- Namespaces which name starts with
kube-oropenshift, an the Namespaceresiliency-operator. - All namespaced objects inside a blacklisted Namespace.
- ConfigMaps named
kube-root-ca.crtoropenshift-service-ca.crt.
Objects path
The files from the bucket will be read as Kubernetes objectsfrom files with the following path: <group>.<version>.<kind>/<object_namespace>.<object_name>.
Examples:
- The Namespace named
testwill be saved in the filecore.v1.Namespace/test. - The Deployment named
app-1deployed in thetestNamespace will be saved in the fileapps.v1.Deployment/test.app-1.
Use cases
Backup restore
Restore your Kubernetes cluster from a Bucket.
Pilot light architecture
Recover from a disaster by running the application saved in the Bucket.
2.2 - Configuration
Introduction
The synchronization process can be configured with some specific parameters using the .spec.config attribute.
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
Required configuration
Source and destination
The source bucket and the destination cluster can be specified using the .spec.config.sourceName and .spec.config.destinationName properties. Both the KubernetesCluster and the bucket objects should exists in the same Namespace where the synchronization is being created.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
sourceName: bucket-1
destinationName: cluster-1
...
Selectors
The resources that should be synchronized can be configured using the .spec.config.selectors property.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
selectors:
- target:
version: v1
resources:
- namespaces
objectSelector:
labelSelector:
matchLabels:
env: pro
Optional configuration
Global selectors
Global selectors are used to set the default value on all selectors defined in .spec.config.selectors. They can be configured with the .spec.config.globalSelector property.
There are two options allowed, that can be configured at the same time:
namespaceSelector: to set e dafult namespace selector for namespaced resourcesobjectSelector: to set a default object selector for all resources
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
globalSelector:
namespaceSelector:
labelSelector:
matchLabels:
env: pro
objectSelector:
labelSelector:
matchLabels:
env: pro
Path prefix
The Kubernetes objects can be written in a subdirectory of the destination Bucket. The property .spec.config.pathPrefix allows this configuration.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
pathPrefix: prefix-path
Log level
The log level of the Pod deployed to execute the synchronization, can be configured with the .spec.config.logLevel parameter.
info.
Accepted values: debug, info, warn, error.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
logLevel: warn
Observability
Observability can be enaled using the specific .spec.config.observability parameter. For more information check the Observability page.
Default value:
enabled: false
interval: 60s
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
observability:
enabled: true
interval: 2m
Limit assigned resources
For each synchronization, a new Pod is deployed inside the same Namespace. The limit and requests resources can be set using the .spec.config.resources field.
{}.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
resources:
requests:
cpu: 1
memory: 2Gi
limits:
cpu: 2
memory: 2Gi
Concurrency
The concurrency parameter can be used to improve the peformance of the synchronization process with .spec.config.concurrency`.
100.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
concurrency: 200
Transformations
Objects from the source bucket can be transformed before being synchronized into the destination cluster.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
transformations:
resources:
- version: v1
resources:
- namespaces
operations:
- jsonpatch:
operations:
- op: add
path: /metadata/labels/test-astrosync
value: ok
API Reference
| Name | Description | Type | Required |
|---|---|---|---|
| sourceName | Bucket name | string | yes |
| destinationName | KubernetesCluster name | string | yes |
| selectors | The Kubernetes resources to be syncrhonized | []KubernetesObjectSelector | yes |
| globalSelector | Global selectors to be applied to all selectors | KubernetesGlobalSelector | yes |
2.3 - Observability
Introduction
The synchronization process exports many metrics in Prometheus format over HTTP.
Exported metrics
The following metrics are available:
| Metric | Description |
|---|---|
astronetes_synchronization_status | The status of each synchronization object. |
astronetes_synchronization_status_total | The count of synchronization objects for each state. |
Requirements
- The
ServiceMonitorCRD from prometheus (servicemonitors.monitoring.coreos.com) must be enabled in the cluster where the operator is running.
Processes
Enable observability
Update the synchronization configuration, setting the paramente .spec.config.observability.enabled to true.
Once enabled the observability, a ServiceMonitor will be created in the same Namespace of the related synchronization.
Disable observability
Update the synchronization configuration, setting the paramente .spec.config.observability.enabled to false.
2.4 - API Reference
Config
Configuration for Bucket to Kubernetes synchronization
| Field | Description | Type | Required |
|---|---|---|---|
concurrency | Concurrent processes to be executed to improve performance | int | false |
destinationName | KubernetesCluster name where data will be synchronized | string | false |
globalSelector | Overrides selectors properties | KubernetesGlobalSelector | false |
logLevel | Log level to be used by the synchronization Pod | string | false |
observability | Observability configuration | ObservabilityConfig | false |
options | Synchronization options | SynchronizationOptions | false |
pathPrefix | Path prefix to be used to retreive objects in the Bucket | string | false |
resources | Resources to be assigned to the synchronization Pod | ResourceRequirements | false |
selectors | Selectors to filter the Kubernetes resources to be synchronized | []KubernetesObjectSelector | false |
sourceName | Bucket name from where data will be read | string | false |
transformations | Transform Kubernetes objects before to be written to the destination | []Transformations | false |
useCachedData | Use cached data instead of get data from Kubernetes clusters on startup | bool | false |
KubernetesGlobalSelector
Global selector is used to set the default value on all selectors
| Field | Description | Type | Required |
|---|---|---|---|
objectSelector | Rules to filter Kubernetes objects by ObjectSelector | ObjectSelector | false |
namespaceSelector | Rules to filter Kubernetes objects by NamespaceSelector | NamespaceSelector | false |
ObjectSelector
| Field | Description | Type | Required |
|---|---|---|---|
nameSelector | Filter objects by their name | NameSelector | false |
labelSelector | Filter objects by their labels | LabelSelector | false |
NameSelector
Select object by their name
| Field | Description | Type | Required |
|---|---|---|---|
includeRegex | Include names that matches at least one regex | []string | false |
excludeRegex | Exlcude names that matches at least one regex | []string | false |
LabelSelector
A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. +structType=atomic
| Field | Description | Type | Required |
|---|---|---|---|
matchLabels | matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabelsmap is equivalent to an element of matchExpressions, whose key field is “key”, theoperator is “In”, and the values array contains only “value”. The requirements are ANDed.+optional | map[string]string | false |
matchExpressions | matchExpressions is a list of label selector requirements. The requirements are ANDed.+optional+listType=atomic | []LabelSelectorRequirement | false |
LabelSelectorRequirement
A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.
| Field | Description | Type | Required |
|---|---|---|---|
key | key is the label key that the selector applies to. | string | false |
operator | operator represents a key’s relationship to a set of values.Valid operators are In, NotIn, Exists and DoesNotExist. | LabelSelectorOperator | false |
values | values is an array of string values. If the operator is In or NotIn,the values array must be non-empty. If the operator is Exists or DoesNotExist,the values array must be empty. This array is replaced during a strategicmerge patch.+optional+listType=atomic | []string | false |
LabelSelectorOperator
A label selector operator is the set of operators that can be used in a selector requirement.
| Field | Description | Type | Required |
|---|
NamespaceSelector
| Field | Description | Type | Required |
|---|---|---|---|
nameSelector | Filter Namespaces by their name | NameSelector | false |
labelSelector | Filter Namespaces by their labels | LabelSelector | false |
ObservabilityConfig
Configure the synchronization process observability using Prometheus ServiceMonitor
| Field | Description | Type | Required |
|---|---|---|---|
enabled | Enable the Observability with a Prometheus ServiceMonitor | bool | false |
interval | Configure the interval in the ServiceMonitor that Prometheus will use to scrape metrics | Duration | false |
Duration
Duration is a wrapper around time.Duration which supports correct marshaling to YAML and JSON. In particular, it marshals into strings, which can be used as map keys in json.
| Field | Description | Type | Required |
|---|
SynchronizationOptions
Customize the synchronization process with special options
| Field | Description | Type | Required |
|---|---|---|---|
dryRun | Simulate the synchronization process but don’t execute the write operations | bool | false |
forceSync | Synchronize object in the destination even if the object exists in the destination and it doesn’t match the configured selectors | bool | false |
forcePrune | Prune object in the destination even if it doesn’t match the configured selectors | bool | false |
showLogIfObjectIsAlreadyInSync | Show a log message if object is already in sync | bool | false |
showLogIfObjectHaveBeenAdapted | Show a log message if object have been adapted for the destination | bool | false |
KubernetesObjectSelector
| Field | Description | Type | Required |
|---|---|---|---|
objectSelector | Filter objects by ObjectSelector | ObjectSelector | false |
namespaceSelector | Filter objects by NamespaceSelector | NamespaceSelector | false |
target | Kubernetes resource to be used | GroupVersionResources | false |
GroupVersionResources
Select a set of GroupVersionResource
| Field | Description | Type | Required |
|---|---|---|---|
group | Kubernetes resource group. Example: apps | string | false |
version | Kubernetes resource version. Example: v1 | string | false |
resources | Kubernetes resource names. Example: deployments | []string | false |
Transformations
Transformations is a list of operations to modifiy the Kubernetes objects matching the given selectors
| Field | Description | Type | Required |
|---|---|---|---|
resources | Select the objects to be transfomred by their resource type | []GroupVersionResources | false |
namespaceSelector | Filter the objects to be transformed by NamespaceSelector | NamespaceSelector | false |
objectSelector | Filter the objects to be transformed by ObjectSelector | ObjectSelector | false |
operations | Operations to be executed to transform the objects | []TransformationOperation | false |
TransformationOperation
The operation to execute to transform the objects
| Field | Description | Type | Required |
|---|---|---|---|
jsonpatch | JSONPatch operation | OperationJSONPatch | false |
OperationJSONPatch
The JSONPatch operation
| Field | Description | Type | Required |
|---|---|---|---|
skipIfNotFoundOnDelete | Skip if not found on delete | bool | false |
operations | List of operations to be executed | []JSONPatchOperation | false |
JSONPatchOperation
JSONPAtch operation
| Field | Description | Type | Required |
|---|---|---|---|
op | JSONPatch operation: add, copy, move, remove, replace, test | string | false |
path | Execute the operation to the given path | string | false |
value | Optional value to be used in the operation | interface{} | false |
3 - Kubernetes to Bucket
3.1 - Introduction
Kubernetes objects can be synchronized into a Bucket the kubernetes-to-bucket plugin.
Synchronization process
Special rules
There are no special rules for this synchronization plugin.
Blacklisted objects
There are some Kubernetes objects that are blacklisted by default and will be ignored by the synchronization process.
This is the list of the blacklisted objects:
- Namespaces which name starts with
kube-oropenshift, an the Namespaceresiliency-operator. - All namespaced objects inside a blacklisted Namespace.
- ConfigMaps named
kube-root-ca.crtoropenshift-service-ca.crt.
Objects path
Each Kubernetes object will be stored into a file with the following path: <group>.<version>.<kind>/<object_namespace>.<object_name>.
Examples:
- The Namespace named
testwill be saved in the filecore.v1.Namespace/test. - The Deployment named
app-1deployed in thetestNamespace will be saved in the fileapps.v1.Deployment/test.app-1.
Use cases
Backups
Backup your Kubernetes cluster to a Bucket to recover data when required.
Pilot light architecture
Synchronize applications to a Bucket and recover the applications in another cluster after a disaster.
3.2 - Configuration
Introduction
The synchronization process can be configured with some specific parameters using the .spec.config attribute.
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
Required configuration
Source and destination
The source cluster and the destination bucket can be specified using the .spec.config.sourceName and .spec.config.destinationName properties. Both the KubernetesCluster and the bucket objects should exists in the same Namespace where the synchronization is being created.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
sourceName: cluster-1
destinationName: bucket-1
...
Optional configuration
Selectors
The resources that should be synchronized can be configured using the .spec.config.selectors property. If not configured, all resources will be included in the synchronization.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
selectors:
- target:
version: v1
resources:
- namespaces
objectSelector:
labelSelector:
matchLabels:
disaster-recovery: "true"
Global selectors
Global selectors are used to set the default value on all selectors defined in .spec.config.selectors. They can be configured with the .spec.config.globalSelector property.
There are two options allowed, that can be configured at the same time:
namespaceSelector: to set e dafult namespace selector for namespaced resourcesobjectSelector: to set a default object selector for all resources
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
globalSelector:
namespaceSelector:
labelSelector:
matchLabels:
env: pro
objectSelector:
labelSelector:
matchLabels:
env: pro
Path prefix
The Kubernetes objects can be written in a subdirectory of the destination Bucket. The property .spec.config.pathPrefix allows this configuration.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
pathPrefix: prefix-path
Log level
The log level of the Pod deployed to execute the synchronization, can be configured with the .spec.config.logLevel parameter.
info.
Accepted values: debug, info, warn, error.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
logLevel: warn
Observability
Observability can be enaled using the specific .spec.config.observability parameter. For more information check the Observability page.
Default value:
enabled: false
interval: 60s
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
observability:
enabled: true
interval: 2m
Limit assigned resources
For each synchronization, a new Pod is deployed inside the same Namespace. The limit and requests resources can be set using the .spec.config.resources field.
{}.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
resources:
requests:
cpu: 1
memory: 2Gi
limits:
cpu: 2
memory: 2Gi
Concurrency
The concurrency parameter can be used to improve the peformance of the synchronization process with .spec.config.concurrency`.
100.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
concurrency: 200
Transformations
Kubernetes obejcts from the source cluster can be transformed before being synchronized into the destination bucket.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-bucket
config:
...
transformations:
resources:
- version: v1
resources:
- namespaces
operations:
- jsonpatch:
operations:
- op: add
path: /metadata/labels/test-astrosync
value: ok
3.3 - Observability
Introduction
The synchronization process exports many metrics in Prometheus format over HTTP.
Exported metrics
The following metrics are available:
| Metric | Description |
|---|---|
astronetes_synchronization_status | The status of each synchronization object. |
astronetes_synchronization_status_total | The count of synchronization objects for each state. |
Requirements
- The
ServiceMonitorCRD from prometheus (servicemonitors.monitoring.coreos.com) must be enabled in the cluster where the operator is running.
Processes
Enable observability
Update the synchronization configuration, setting the paramente .spec.config.observability.enabled to true.
Once enabled the observability, a ServiceMonitor will be created in the same Namespace of the related synchronization.
Disable observability
Update the synchronization configuration, setting the paramente .spec.config.observability.enabled to false.
3.4 - API Reference
Config
Configuration for Kubernetes to Bucket synchronization
| Field | Description | Type | Required |
|---|---|---|---|
concurrency | Concurrent processes to be executed to improve performance | int | false |
destinationName | Bucket name where data will be synchronized | string | false |
globalSelector | Overrides selectors properties | KubernetesGlobalSelector | false |
logLevel | Log level to be used by the synchronization Pod | string | false |
observability | Observability configuration | ObservabilityConfig | false |
options | Synchronization options | SynchronizationOptions | false |
pathPrefix | Path prefix to be used to retreive objects in the Bucket | string | false |
resources | Resources to be assigned to the synchronization Pod | ResourceRequirements | false |
selectors | Selectors to filter the Kubernetes resources to be synchronized | []KubernetesObjectSelector | false |
sourceName | KubernetesCluster name from where data will be read | string | false |
transformations | Transform Kubernetes objects before to be written to the destination | []Transformations | false |
useCachedData | Use cached data instead of get data from assets on startup | bool | false |
KubernetesGlobalSelector
Global selector is used to set the default value on all selectors
| Field | Description | Type | Required |
|---|---|---|---|
objectSelector | Rules to filter Kubernetes objects by ObjectSelector | ObjectSelector | false |
namespaceSelector | Rules to filter Kubernetes objects by NamespaceSelector | NamespaceSelector | false |
ObjectSelector
| Field | Description | Type | Required |
|---|---|---|---|
nameSelector | Filter objects by their name | NameSelector | false |
labelSelector | Filter objects by their labels | LabelSelector | false |
NameSelector
Select object by their name
| Field | Description | Type | Required |
|---|---|---|---|
includeRegex | Include names that matches at least one regex | []string | false |
excludeRegex | Exlcude names that matches at least one regex | []string | false |
LabelSelector
A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects. +structType=atomic
| Field | Description | Type | Required |
|---|---|---|---|
matchLabels | matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabelsmap is equivalent to an element of matchExpressions, whose key field is “key”, theoperator is “In”, and the values array contains only “value”. The requirements are ANDed.+optional | map[string]string | false |
matchExpressions | matchExpressions is a list of label selector requirements. The requirements are ANDed.+optional+listType=atomic | []LabelSelectorRequirement | false |
LabelSelectorRequirement
A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.
| Field | Description | Type | Required |
|---|---|---|---|
key | key is the label key that the selector applies to. | string | false |
operator | operator represents a key’s relationship to a set of values.Valid operators are In, NotIn, Exists and DoesNotExist. | LabelSelectorOperator | false |
values | values is an array of string values. If the operator is In or NotIn,the values array must be non-empty. If the operator is Exists or DoesNotExist,the values array must be empty. This array is replaced during a strategicmerge patch.+optional+listType=atomic | []string | false |
LabelSelectorOperator
A label selector operator is the set of operators that can be used in a selector requirement.
| Field | Description | Type | Required |
|---|
NamespaceSelector
| Field | Description | Type | Required |
|---|---|---|---|
nameSelector | Filter Namespaces by their name | NameSelector | false |
labelSelector | Filter Namespaces by their labels | LabelSelector | false |
ObservabilityConfig
Configure the synchronization process observability using Prometheus ServiceMonitor
| Field | Description | Type | Required |
|---|---|---|---|
enabled | Enable the Observability with a Prometheus ServiceMonitor | bool | false |
interval | Configure the interval in the ServiceMonitor that Prometheus will use to scrape metrics | Duration | false |
Duration
Duration is a wrapper around time.Duration which supports correct marshaling to YAML and JSON. In particular, it marshals into strings, which can be used as map keys in json.
| Field | Description | Type | Required |
|---|
SynchronizationOptions
Customize the synchronization process with special options
| Field | Description | Type | Required |
|---|---|---|---|
dryRun | Simulate the synchronization process but don’t execute the write operations | bool | false |
forceSync | Synchronize object in the destination even if the object exists in the destination and it doesn’t match the configured selectors | bool | false |
forcePrune | Prune object in the destination even if it doesn’t match the configured selectors | bool | false |
showLogIfObjectIsAlreadyInSync | Show a log message if object is already in sync | bool | false |
showLogIfObjectHaveBeenAdapted | Show a log message if object have been adapted for the destination | bool | false |
KubernetesObjectSelector
| Field | Description | Type | Required |
|---|---|---|---|
objectSelector | Filter objects by ObjectSelector | ObjectSelector | false |
namespaceSelector | Filter objects by NamespaceSelector | NamespaceSelector | false |
target | Kubernetes resource to be used | GroupVersionResources | false |
GroupVersionResources
Select a set of GroupVersionResource
| Field | Description | Type | Required |
|---|---|---|---|
group | Kubernetes resource group. Example: apps | string | false |
version | Kubernetes resource version. Example: v1 | string | false |
resources | Kubernetes resource names. Example: deployments | []string | false |
Transformations
Transformations is a list of operations to modifiy the Kubernetes objects matching the given selectors
| Field | Description | Type | Required |
|---|---|---|---|
resources | Select the objects to be transfomred by their resource type | []GroupVersionResources | false |
namespaceSelector | Filter the objects to be transformed by NamespaceSelector | NamespaceSelector | false |
objectSelector | Filter the objects to be transformed by ObjectSelector | ObjectSelector | false |
operations | Operations to be executed to transform the objects | []TransformationOperation | false |
TransformationOperation
The operation to execute to transform the objects
| Field | Description | Type | Required |
|---|---|---|---|
jsonpatch | JSONPatch operation | OperationJSONPatch | false |
OperationJSONPatch
The JSONPatch operation
| Field | Description | Type | Required |
|---|---|---|---|
skipIfNotFoundOnDelete | Skip if not found on delete | bool | false |
operations | List of operations to be executed | []JSONPatchOperation | false |
JSONPatchOperation
JSONPAtch operation
| Field | Description | Type | Required |
|---|---|---|---|
op | JSONPatch operation: add, copy, move, remove, replace, test | string | false |
path | Execute the operation to the given path | string | false |
value | Optional value to be used in the operation | interface{} | false |
4 - Kubernetes to Kubernetes
4.1 - Introduction
Kubernetes objects can be synchronized between clusters adopting the kubernetes-to-kubernetes plugin.
Synchronization process
Special rules
Additionally, there are some special rules for source kind of objects:
PersistentVolumeClaim: objects will be updated in the destination cluster only if
.spec.resourceschanges.ServiceAccount: If you’re using a Kubernetes cluster version <v1.24, when creating a ServiceAccount, an autogenerated secret will be created. From here, there are two scenarios:
Service account with an autogenerated secret: The autogenerated secret will be deleted, and a new one will be generated in the target cluster. The secret is always updated during each synchronization.
Service account with a custom secret: The custom secret will remain unchanged.
To avoid errors, custom secrets must not follow the autogenerated secret naming structure. Secrets are considered autogenerated if they begin with the following prefixes:
{serviceAccountName}-token-{serviceAccountName}-dockercfg-
Blacklisted objects
There are some Kubernetes objects that are blacklisted by default and will be ignored by the synchronization process.
This is the list of the blacklisted objects:
- Namespaces which name starts with
kube-oropenshift, and the Namespaceresiliency-operator. - All namespaced objects inside a blacklisted Namespace.
- ConfigMaps named
kube-root-ca.crtoropenshift-service-ca.crt.
4.2 - Configuration
Introduction
The synchronization process can be configured with some specific parameters using the .spec.config attribute.
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
...
Required configuration
Source and destination
The source and the destination clusters can be specified using the .spec.config.sourceName and .spec.config.destinationName properties. Both KubernetesCluster objects should exists in the same Namespace where the synchronization is being created.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
sourceName: cluster-1
destinationName: cluster-2
...
Selectors
The resources that should be synchronized between clusters can be configured using the .spec.config.selectors property.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
...
selectors:
- target:
version: v1
resources:
- namespaces
objectSelector:
labelSelector:
matchLabels:
disaster-recovery: "true"
Optional configuration
Global selectors
Global selectors are used to set the default value on all selectors defined in .spec.config.selectors. They can be configured with the .spec.config.globalSelector property.
There are two options allowed, that can be configured at the same time:
namespaceSelector: to set e dafult namespace selector for namespaced resourcesobjectSelector: to set a default object selector for all resources
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: bucket-to-kubernetes
config:
...
globalSelector:
namespaceSelector:
labelSelector:
matchLabels:
env: pro
objectSelector:
labelSelector:
matchLabels:
env: pro
Log level
The log level of the Pod deployed to execute the synchronization, can be configured with the .spec.config.logLevel parameter.
info.
Accepted values: debug, info, warn, error.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
...
logLevel: warn
Observability
Observability can be enaled using the specific .spec.config.observability parameter.
Default value:
enabled: false
interval: 60s
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
...
observability:
enabled: true
interval: 2m
Limit assigned resources
For each synchronization, a new Pod is deployed inside the same Namespace. The limit and requests resources can be set using the .spec.config.resources field.
{}.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
...
resources:
requests:
cpu: 1
memory: 2Gi
limits:
cpu: 2
memory: 2Gi
Concurrency
The concurrency parameter can be used to improve the peformance of the synchronization process with .spec.config.concurrency`.
100.Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
...
concurrency: 200
Transformations
Kubernetes obejcts from the source cluster can be transformed before being synchronized into the destination cluster.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: kubernetes-to-kubernetes
config:
...
transformations:
- resources:
- group: ""
version: v1
resources:
- namespaces
namespaceSelector:
labelSelector:
matchLabels:
sync: "true"
operations:
- jsonpatch:
operations:
- op: add
path: /metadata/labels/test-astrosync
value: ok
4.3 - Observability
Introduction
The synchronization process exports many metrics in Prometheus format over HTTP.
Exported metrics
The following metrics are available:
| Metric | Description |
|---|---|
astronetes_synchronization_status | The status of each synchronization object. |
astronetes_synchronization_status_total | The count of synchronization objects for each state. |
Requirements
- The
ServiceMonitorCRD from prometheus (servicemonitors.monitoring.coreos.com) must be enabled in the cluster where the operator is running.
Processes
Enable observability
Update the synchronization configuration, setting the paramente .spec.config.observability.enabled to true.
Once enabled the observability, a ServiceMonitor will be created in the same Namespace of the related synchronization.
Disable observability
Update the synchronization configuration, setting the paramente .spec.config.observability.enabled to false.
4.4 - API Reference
Config
Configuration for Kubernetes to Kubernetes synchronization
| Field | Description | Type | Required |
|---|---|---|---|
concurrency | Concurrent processes to be executed to improve performance | int | false |
destinationName | KubernetesCluster name where data will be synchronized | string | false |
globalSelector | Overrides selectors properties | KubernetesGlobalSelector | false |
logLevel | Log level to be used by the synchronization Pod | string | false |
observability | Observability configuration | ObservabilityConfig | false |
options | Synchronization options | SynchronizationOptions | false |
resources | Resources to be assigned to the synchronization Pod | ResourceRequirements | false |
selectors | Selectors to filter the Kubernetes resources to be synchronized | []KubernetesObjectSelector | false |
sourceName | KubernetesCluster name from where data will be read | string | false |
transformations | Transform Kubernetes objects before to be written to the destination | []Transformations | false |
useCachedData | Use cached data instead of get data from Kubernetes clusters on startup | bool | false |
KubernetesGlobalSelector
Global selector is used to set the default value on all selectors
| Field | Description | Type | Required |
|---|---|---|---|
objectSelector | Rules to filter Kubernetes objects by ObjectSelector | ObjectSelector | false |
namespaceSelector | Rules to filter Kubernetes objects by NamespaceSelector | NamespaceSelector | false |
ObjectSelector
| Field | Description | Type | Required |
|---|---|---|---|
nameSelector | Filter objects by their name | NameSelector | false |
labelSelector | Filter objects by their labels | LabelSelector | false |
NameSelector
Select object by their name
| Field | Description | Type | Required |
|---|---|---|---|
includeRegex | Include names that matches at least one regex | []string | false |
excludeRegex | Exlcude names that matches at least one regex | []string | false |
LabelSelector
Select object by their labels
| Field | Description | Type | Required |
|---|---|---|---|
matchLabels | Match object by the given labels | map[string]string | false |
matchExpressions | Match object by the given expressions | []LabelSelectorRequirement | false |
LabelSelectorRequirement
A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.
| Field | Description | Type | Required |
|---|---|---|---|
key | key is the label key that the selector applies to. | string | false |
operator | operator represents a key’s relationship to a set of values.Valid operators are In, NotIn, Exists and DoesNotExist. | LabelSelectorOperator | false |
values | values is an array of string values. If the operator is In or NotIn,the values array must be non-empty. If the operator is Exists or DoesNotExist,the values array must be empty. This array is replaced during a strategicmerge patch.+optional+listType=atomic | []string | false |
LabelSelectorOperator
A label selector operator is the set of operators that can be used in a selector requirement.
| Field | Description | Type | Required |
|---|
NamespaceSelector
| Field | Description | Type | Required |
|---|---|---|---|
nameSelector | Filter Namespaces by their name | NameSelector | false |
labelSelector | Filter Namespaces by their labels | LabelSelector | false |
ObservabilityConfig
Configure the synchronization process observability using Prometheus ServiceMonitor
| Field | Description | Type | Required |
|---|---|---|---|
enabled | Enable the Observability with a Prometheus ServiceMonitor | bool | false |
interval | Configure the interval in the ServiceMonitor that Prometheus will use to scrape metrics | Duration | false |
Duration
Duration is a wrapper around time.Duration which supports correct marshaling to YAML and JSON. In particular, it marshals into strings, which can be used as map keys in json.
| Field | Description | Type | Required |
|---|
SynchronizationOptions
Customize the synchronization process with special options
| Field | Description | Type | Required |
|---|---|---|---|
dryRun | Simulate the synchronization process but don’t execute the write operations | bool | false |
forceSync | Synchronize object in the destination even if the object exists in the destination and it doesn’t match the configured selectors | bool | false |
forcePrune | Prune object in the destination even if it doesn’t match the configured selectors | bool | false |
showLogIfObjectIsAlreadyInSync | Show a log message if object is already in sync | bool | false |
showLogIfObjectHaveBeenAdapted | Show a log message if object have been adapted for the destination | bool | false |
KubernetesObjectSelector
| Field | Description | Type | Required |
|---|---|---|---|
objectSelector | Filter objects by ObjectSelector | ObjectSelector | false |
namespaceSelector | Filter objects by NamespaceSelector | NamespaceSelector | false |
target | Kubernetes resource to be used | GroupVersionResources | false |
GroupVersionResources
Select a set of GroupVersionResource
| Field | Description | Type | Required |
|---|---|---|---|
group | Kubernetes resource group. Example: apps | string | false |
version | Kubernetes resource version. Example: v1 | string | false |
resources | Kubernetes resource names. Example: deployments | []string | false |
Transformations
Transformations is a list of operations to modifiy the Kubernetes objects matching the given selectors
| Field | Description | Type | Required |
|---|---|---|---|
resources | Select the objects to be transfomred by their resource type | []GroupVersionResources | false |
namespaceSelector | Filter the objects to be transformed by NamespaceSelector | NamespaceSelector | false |
objectSelector | Filter the objects to be transformed by ObjectSelector | ObjectSelector | false |
operations | Operations to be executed to transform the objects | []TransformationOperation | false |
TransformationOperation
The operation to execute to transform the objects
| Field | Description | Type | Required |
|---|---|---|---|
jsonpatch | JSONPatch operation | OperationJSONPatch | false |
OperationJSONPatch
The JSONPatch operation
| Field | Description | Type | Required |
|---|---|---|---|
skipIfNotFoundOnDelete | Skip if not found on delete | bool | false |
operations | List of operations to be executed | []JSONPatchOperation | false |
JSONPatchOperation
JSONPAtch operation
| Field | Description | Type | Required |
|---|---|---|---|
op | JSONPatch operation: add, copy, move, remove, replace, test | string | false |
path | Execute the operation to the given path | string | false |
value | Optional value to be used in the operation | interface{} | false |
5 - Zookeeper to Zookeeper
5.1 - Introduction
You can synchronize Zookeeper data between two clusters using the Zookeeper protocol.
Supported models
One time synchronization
You can synchronize the data just once with the Synchronization Kubernetes object.
Periodic synchronization
You can synchronize periodically the SynchronizationPlan Kubernetes object.
Samples
Synchronize once
Synchronize the data once only in the /test path:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
generateName: synchronize-zookeeper-
spec:
plugin: zookeeper-to-zookeeper-nodes
config:
sourceName: zookeeper-source
destinationName: zookeeper-destination
rootPath: /test
createRoutePath: true
Scheduled synchronization
Synchronize data every hour in the /test path:
apiVersion: automation.astronetes.io/v1alpha1
kind: SynchronizationPlan
metadata:
name: synchronize-zookeeper
spec:
schedule: "0 * * * *"
template:
spec:
plugin: zookeeper-to-zookeeper-nodes
config:
sourceName: zookeeper-source
destinationName: zookeeper-destination
rootPath: /test
5.2 - Configuration
Required configuration
Source and destination
The source and the destination clusters can be specified using the .spec.config.sourceName and .spec.config.destinationName properties. Both Database objects should exists in the same Namespace where the synchronization is being created.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: zookeeper-nodes-to-zookeeper
config:
sourceName: cluster-1
destinationName: cluster-2
...
Root path
The root path to be used to only synchronize a specific part of the Zookeeper database.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: zookeeper-nodes-to-zookeeper
config:
...
rootPath: /test
Optional configuration
Create root path
Create the Root Path in the destination database if it doesn’t exist.
falseExample:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: zookeeper-nodes-to-zookeeper
config:
...
createRootPath: true
Ignore ephemeral
Don’t synchronize ephemeral data in the destination cluster..
falseExample:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: zookeeper-nodes-to-zookeeper
config:
...
ignoreEphemeral: true
Exclude paths
Exclude data from being synchronized to the destination cluster filtering on path using regex.
Example:
apiVersion: automation.astronetes.io/v1alpha1
kind: Synchronization
metadata:
name: example
spec:
plugin: zookeeper-nodes-to-zookeeper
config:
...
excludeRegex: ..
5.3 - API Reference
Config
Configuration for Zookeeper to Zookeeper synchronization
| Name | Description | Type | Required |
|---|---|---|---|
sourceName | Zookeeper instance acting as source | string | yes |
destinationName | Zookeeper instance acting as destination | string | yes |
rootPath | Root Path of the contents to synchronize | string | yes |
createRootPath | Whether to create the Root Path in the destination database | boolean | no |
ignoreEphemeral | Whether to ignore ephemeral | boolean | no |
excludePathRegexp | Regular expression for keys to exclude while synchronizing | string | no |