Crane is a migration tool under the Konveyor community that helps application owners migrate Kubernetes workloads and their state between clusters.
Migrating an application between Kubernetes clusters may be more nuanced than one would imagine. In an ideal situation, this would be as simple as applying the YAML manifests to the new cluster and adjusting DNS records to redirect external traffic, yet often there is more that is needed. Below are a few of the common concerns that need to be addressed:
Crane helps users do more than just handle a point in time migration of a workload, it is intended to help users adopt current best practices such as onboarding to GitOps by reconstructing redeployable YAML manifests from inspecting a running application. The project is the result of several years of experience performing large-scale production Kubernetes migrations and addressing the lessons learned.
Crane follows the Unix philosophy of building small sharply focused tools that can be assembled in powerful ways. It is designed with transparency and ease-of-diagnostics in mind. It drives migration through a pipeline of non-destructive tasks that output results to disk so the operation can be easily audited and versioned without impacting live workloads. The tasks can be run repeatedly and will output consistent results given the same inputs without side-effects on the system at large.
Crane is composed of several repositories:
How does it work? Crane works by: 1) Inspecting a running application and exporting all associated resources 2) Leveraging a library of plugins to aid in transforming the exported manifests to yield redeployable manifests 3) Applying the transformed manifests into the destination cluster 4) Optionally orchestrating persistent state migrations
crane
binary from either:
go build -o crane main.go
crane
binary in your $PATH
$ kubectl create namespace guestbook
$ kubectl --namespace guestbook apply -k github.com/konveyor/crane-runner/examples/resources/guestbook
$ crane export -n guestbook
$ cat export/resources/guestbook/Secret_guestbook_builder-dockercfg-5ztj6.yaml
kind: Secret
apiVersion: v1
metadata:
name: builder-dockercfg-5ztj6
namespace: guestbook
resourceVersion: "3213488"
uid: 8fb75dcd-68b2-4939-bfb9-1c8241a7b146
...
data:
.dockercfg: < ...SNIP.... >
$ crane transform
$ cat transform/resources/guestbook/transform-Secret_guestbook_builder-dockercfg-5ztj6.yaml
[{"op":"remove","path":"/metadata/uid"},{"op":"remove","path":"/metadata/resourceVersion"},{"op":"remove","path":"/metadata/creationTimestamp"}]
$ crane apply
A directory output/resources/guestbook/
is populated with redeployable YAML content, this is the result of the 'export' content modified via the transforms produced by 'transform'.
Example:
$ cat output/resources/guestbook/Secret_guestbook_builder-dockercfg-5ztj6.yaml
kind: Secret
apiVersion: v1
metadata:
name: builder-dockercfg-5ztj6
namespace: guestbook
...
data:
.dockercfg: < ...SNIP.... >
Note, that the fields 'metadata.uid', 'metadata.resourceVersion', and 'metadata.creationTimestamp' are removed from this YAML.
The content in the output/resources/guestbook
directory is now ready to be used as needed, this could be redeployed to a new cluster or checked into Git to be leveraged with a GitOps solution.
Please see konveyor/crane-runner/main/examples for further scenarios to explore what can be done with Crane + Tekton for migrating applications.
metadata.namespace
will be
modified, but other required changes will not be made. It will be
removed from this plugin in the next release and expanded
functionality will most likely be added via a separate (optional)
plugin.