diff --git a/content/rancher/v2.x/en/v1.6-migration/_index.md b/content/rancher/v2.x/en/v1.6-migration/_index.md index 9ad773c4f4a..122f98ec1dc 100644 --- a/content/rancher/v2.x/en/v1.6-migration/_index.md +++ b/content/rancher/v2.x/en/v1.6-migration/_index.md @@ -3,13 +3,13 @@ title: Migrating from Rancher v1.6 Cattle to v2.x weight: 10000 --- -Rancher 2.0 has been rearchitected and rewritten with the goal of providing a complete management solution for Kubernetes and Docker. Due to these extensive changes, there is no direct upgrade path from 1.6.x to 2.x, but rather a migration of your 1.6 application workloads into the 2.0 Kubernetes equivalent. In 1.6, the most common orchestration used was Rancher's own engine called Cattle. The following blogs (that will be converted in an official guide) explain and educate our Cattle users on running workloads in a Kubernetes environment. +Rancher 2.x has been rearchitected and rewritten with the goal of providing a complete management solution for Kubernetes and Docker. Due to these extensive changes, there is no direct upgrade path from 1.6.x to 2.x, but rather a migration of your 1.6 application workloads into the 2.x Kubernetes equivalent. In 1.6, the most common orchestration used was Rancher's own engine called Cattle. The following blogs (that will be converted in an official guide) explain and educate our Cattle users on running workloads in a Kubernetes environment. -If you are an existing Kubernetes user on Rancher 1.6, you only need to review the [Get Started](#1-get-started) section to prepare you on what to expect on a new 2.0 Rancher cluster. +If you are an existing Kubernetes user on Rancher 1.6, you only need to review the [Get Started](#1-get-started) section to prepare you on what to expect on a new 2.x Rancher cluster. ## Kubernetes Basics -Rancher 2.0 is built on the [Kubernetes](https://kubernetes.io/docs/home/?path=users&persona=app-developer&level=foundational) container orchestrator. This shift in underlying technology for 2.0 is a large departure from 1.6, which supported several popular container orchestrators. Since Rancher is now based entirely on Kubernetes, it's helpful to learn the Kubernetes basics. +Rancher 2.x is built on the [Kubernetes](https://kubernetes.io/docs/home/?path=users&persona=app-developer&level=foundational) container orchestrator. This shift in underlying technology for 2.x is a large departure from 1.6, which supported several popular container orchestrators. Since Rancher is now based entirely on Kubernetes, it's helpful to learn the Kubernetes basics. The following table introduces and defines some key Kubernetes concepts. @@ -25,9 +25,9 @@ The following table introduces and defines some key Kubernetes concepts. ## Migration Cheatsheet -Because Rancher 1.6 defaulted to our Cattle container orchestrator, it primarily used terminology related to Cattle. However, because Rancher 2.0 uses Kubernetes, it aligns with the Kubernetes naming standard. This shift could be confusing for people unfamiliar with Kubernetes, so we've created a table that maps terms commonly used in Rancher 1.6 to their equivalents in Rancher 2.0. +Because Rancher 1.6 defaulted to our Cattle container orchestrator, it primarily used terminology related to Cattle. However, because Rancher 2.x uses Kubernetes, it aligns with the Kubernetes naming standard. This shift could be confusing for people unfamiliar with Kubernetes, so we've created a table that maps terms commonly used in Rancher 1.6 to their equivalents in Rancher 2.x. -| **Rancher 1.6** | **Rancher 2.0** | +| **Rancher 1.6** | **Rancher 2.x** | | --- | --- | | Container | Pod | | Services | Workload | @@ -58,23 +58,23 @@ More detailed information on Kubernetes concepts can be found in the ## 1. Get Started -As a Rancher 1.6 user who's interested in moving to 2.0, how should you get started with migration? The following blog provides a short checklist to help with this transition. +As a Rancher 1.6 user who's interested in moving to 2.x, how should you get started with migration? The following blog provides a short checklist to help with this transition. -Blog Post: [Migrating from Rancher 1.6 to Rancher 2.0—A Short Checklist](https://rancher.com/blog/2018/2018-08-09-migrate-1dot6-setup-to-2dot0/) +Blog Post: [Migrating from Rancher 1.6 to Rancher 2.x—A Short Checklist](https://rancher.com/blog/2018/2018-08-09-migrate-1dot6-setup-to-2dot0/) ## 2. Run Migration-Tools CLI -The migration-tools CLI is a tool that helps you recreate your applications in Rancher v2.0. This tool exports your Rancher v1.6 applications as Docker Compose files and converts them to a Kubernetes manifest that Rancher 2.0 can consume. +The migration-tools CLI is a tool that helps you recreate your applications in Rancher v2.x. This tool exports your Rancher v1.6 applications as Compose files and converts them to a Kubernetes manifest that Rancher 2.x can consume. This command line interface tool: -- Exports Docker Compose files (i.e., `docker-compose.yml` and `rancher-compose.yml`) from your stacks running on `cattle` environments in your Rancher 1.6 system. For every stack, files are exported to the `//` folder. +- Exports Compose files (i.e., `docker-compose.yml` and `rancher-compose.yml`) for all your stacks that are Cattle environments in your Rancher 1.6 server. For every stack, files are exported to a `//` folder. -- Parses Docker Compose files that you've exported from your Rancher 1.6 Stacks and converts them to a Kubernetes manifest that Rancher v2.0 can consume. The tool also outputs a list of constructs present in the Compose files that cannot be ported automatically to Rancher 2.0—you'll have to port them manually. +- Parses Compose files that you've exported from your Rancher 1.6 stack and converts them to a Kubernetes manifest that Rancher v2.x can consume. The tool also outputs a list of constructs present in the Compose files that cannot be converted automatically to Rancher 2.x. These are fields that you'll have to manually configure in the Kubernetes YAML. ### A. Download Migration-Tools CLI -The migration-tools CLI for your platform can be downloaded from our [GitHub releases page](https://github.com/rancher/migration-tools/releases). The tools are available for Linux, Mac, and Windows platforms. +The migration-tools CLI for your platform can be downloaded from our [GitHub releases page](https://github.com/rancher/migration-tools/releases). The tools are available for Linux, Mac, and Windows platforms. ### B. Configure Migration-Tools CLI @@ -83,7 +83,7 @@ After the tools are downloaded, you need to make some configurations to run them 1. Modify the migration-tools CLI file to make it an executable. - 1. Open Terminal and change to the directory that contains the migration-tool file. + 1. Open Terminal and change to the directory that contains the migration-tools file. 1. Rename the file to `migration-tools` so that it no longer includes the platform name. @@ -95,81 +95,72 @@ After the tools are downloaded, you need to make some configurations to run them ### C. Run Migration-Tools CLI -Next, use the migration-tools CLI to export your Cattle environments from Rancher 1.6 as Docker Compose files. Then, for environments that you want to migrate to Rancher 2.0, convert its Compose file into Kubernetes YAML. +Next, use the migration-tools CLI to export all stacks in all of the Cattle environments into Compose files. Then, for stacks that you want to migrate to Rancher 2.x, convert the Compose files into Kubernetes YAML. >**Want full usage and options for the migration-tools CLI?** See the [Migration-Tools CLI Reference]({{< baseurl >}}/rancher/v2.x/en/v1.6-migration/migration-tools-ref). -1. Export the Docker Compose files for your Cattle environments from Rancher 1.6. +1. Export the Compose files for all stacks in all of the Cattle environments in your Rancher 1.6 server. - From Terminal, execute the following command, replacing each placeholder with your values. + Execute the following command, replacing each placeholder with your values. The access key and secret key are Account API keys, which will allow you to export from all Cattle environments. ``` migration-tools export --url --access-key --secret-key --export-dir ``` - **Step Result:** The migration-tools CLI exports Compose files for each of your Cattle environments in the `--export-dir` directory. If you omitted this option, Compose files are output to your current directory. + **Step Result:** The migration-tools CLI exports Compose files for each stack in every Cattle environments in the `--export-dir` directory. If you omitted this option, the files are saved to your current directory. -1. Convert the exported Compose files to Kubernetes YAML. +1. Convert the exported Compose files for a stack to Kubernetes YAML. - Execute the following command, replacing each placeholder with the absolute path to your Stack's Compose files. If you want to migrate multiple stacks, you'll have to re-run the command for each pair of Compose files that you exported. + Execute the following command, replacing each placeholder with the absolute path to your Stack's Compose files. For each stack, you'll have to re-run the command for each pair of Compose files that was exported. ``` migration-tools parse --docker-file --rancher-file ``` - >**Note:** If you omit the `--docker-file` and `--rancher-file` options from your command, the migration-tools CLI checks its home directory for Compose files. + >**Note:** If you omit the `--docker-file` and `--rancher-file` options from your command, the migration-tools CLI checks its home directory for these Compose files. - -#### Output - -After you run the migration-tools cli `parse` command, the following files are output to your target directory. - -| Output | Description | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `output.txt` | This file lists all constructs for each service in `docker-compose.yml` that requires special handling to be successfully migrated to Rancher 2.0. Each construct links to the relevant blog articles on how to implement it in Rancher 2.0 (these articles are also listed below). | -| Kubernetes YAML specs | Mirgation-tools internally invokes [Kompose](https://github.com/kubernetes/kompose) to generate Kubernetes YAML specs for each service you're migrating to 2.0. Each YAML spec file is named for the service you're migrating. + **Step Result:** The migration-tools CLI parses your Compose files and outputs Kubernetes YAML specs as well as an `output.txt` file. For each service in the stack, a YAML spec file is created and named the same as your service. The `output.txt` file lists all constructs for each service in `docker-compose.yml` that requires special handling to be successfully migrated to Rancher 2.x. Each construct links to the relevant blog articles on how to implement it in Rancher 2.x (these articles are also listed below). ## 3. Migrate Applications -In Rancher 1.6, you launch applications as _services_ and organize them under _stacks_ in an _environment_, which represents a compute and administrative boundary. Rancher 1.6 supports the Docker compose standard and provides import/export for application configurations using the following files: `docker-compose.yml` and `rancher-compose.yml`. In 2.0 the environment concept doesn't exist. Instead it's replaced by: +In Rancher 1.6, you launch applications as _services_ and organize them under _stacks_ in an _environment_, which represents a compute and administrative boundary. Rancher 1.6 supports the Docker compose standard and provides import/export for application configurations using the following files: `docker-compose.yml` and `rancher-compose.yml`. In 2.x the environment concept doesn't exist. Instead it's replaced by: - **Cluster:** The compute boundary. - **Project:** An administrative boundary. -The following article explores how to map Cattle's stack and service design to Kubernetes. It also demonstrates how to migrate a simple application from Rancher 1.6 to 2.0 using either the Rancher UI or Docker Compose. +The following article explores how to map Cattle's stack and service design to Kubernetes. It also demonstrates how to migrate a simple application from Rancher 1.6 to 2.x using either the Rancher UI or Docker Compose. Blog Post: [A Journey from Cattle to Kubernetes!](https://rancher.com/blog/2018/2018-08-02-journey-from-cattle-to-k8s/) ## 4. Expose Your Services -In Rancher 1.6, you could provide external access to your applications using port mapping. This article explores how to publicly expose your services in Rancher 2.0. It explores both UI and CLI methods to transition the port mapping functionality. +In Rancher 1.6, you could provide external access to your applications using port mapping. This article explores how to publicly expose your services in Rancher 2.x. It explores both UI and CLI methods to transition the port mapping functionality. -Blog Post: [From Cattle to Kubernetes—How to Publicly Expose Your Services in Rancher 2.0](https://rancher.com/blog/2018/expose-and-monitor-workloads/) +Blog Post: [From Cattle to Kubernetes—How to Publicly Expose Your Services in Rancher 2.x](https://rancher.com/blog/2018/expose-and-monitor-workloads/) ## 5. Monitor Your Applications -Rancher 1.6 provided TCP and HTTP healthchecks using its own healthcheck microservice. Rancher 2.0 uses native Kubernetes healthcheck support instead. This article overviews how to configure it in Rancher 2.0. +Rancher 1.6 provided TCP and HTTP healthchecks using its own healthcheck microservice. Rancher 2.x uses native Kubernetes healthcheck support instead. This article overviews how to configure it in Rancher 2.x. -Blog Post: [From Cattle to Kubernetes—Application Healthchecks in Rancher 2.0](https://rancher.com/blog/2018/2018-08-22-k8s-monitoring-and-healthchecks/) +Blog Post: [From Cattle to Kubernetes—Application Healthchecks in Rancher 2.x](https://rancher.com/blog/2018/2018-08-22-k8s-monitoring-and-healthchecks/) ## 6. Schedule Deployments -Scheduling application containers on available resources is a key container orchestration technique. The following blog reviews how to schedule containers in Rancher 2.0 for those familiar with 1.6 scheduling labels (such as affinity and anti-affinity). It also explores how to launch a global service in 2.0. +Scheduling application containers on available resources is a key container orchestration technique. The following blog reviews how to schedule containers in Rancher 2.x for those familiar with 1.6 scheduling labels (such as affinity and anti-affinity). It also explores how to launch a global service in 2.x. -Blog Post: [From Cattle to Kubernetes—Scheduling Workloads in Rancher 2.0](https://rancher.com/blog/2018/2018-08-29-scheduling-options-in-2-dot-0/) +Blog Post: [From Cattle to Kubernetes—Scheduling Workloads in Rancher 2.x](https://rancher.com/blog/2018/2018-08-29-scheduling-options-in-2-dot-0/) ## 7. Service Discovery -Rancher 1.6 provides service discovery within and across stacks using its own internal DNS microservice. It also supports pointing to external services and creating aliases. Moving to Rancher 2.0, you can replicate this same service discovery behavior. The following blog reviews this topic and the solutions needed to achieve service discovery parity in Rancher 2.0. +Rancher 1.6 provides service discovery within and across stacks using its own internal DNS microservice. It also supports pointing to external services and creating aliases. Moving to Rancher 2.x, you can replicate this same service discovery behavior. The following blog reviews this topic and the solutions needed to achieve service discovery parity in Rancher 2.x. -Blog Post: [From Cattle to Kubernetes—Service Discovery in Rancher 2.0](https://rancher.com/blog/2018/2018-09-04-service_discovery_2dot0/) +Blog Post: [From Cattle to Kubernetes—Service Discovery in Rancher 2.x](https://rancher.com/blog/2018/2018-09-04-service_discovery_2dot0/) ## 8. Load Balancing -How to achieve TCP/HTTP load balancing and configure hostname/path-based routing in Rancher 2.0. +How to achieve TCP/HTTP load balancing and configure hostname/path-based routing in Rancher 2.x. -Blog Post: [From Cattle to Kubernetes-How to Load Balance Your Services in Rancher 2.0](https://rancher.com/blog/2018/2018-09-13-load-balancing-options-2dot0/) - -In Rancher 1.6, a Load Balancer was used to expose your applications from within the Rancher environment for external access. In Rancher 2.0, the concept is the same. There is a Load Balancer option to expose your services. In the language of Kubernetes, this function is more often referred to as an **Ingress**. In short, Load Balancer and Ingress play the same role. +Blog Post: [From Cattle to Kubernetes-How to Load Balance Your Services in Rancher 2.x](https://rancher.com/blog/2018/2018-09-13-load-balancing-options-2dot0/) +In Rancher 1.6, a Load Balancer was used to expose your applications from within the Rancher environment for external access. In Rancher 2.x, the concept is the same. There is a Load Balancer option to expose your services. In the language of Kubernetes, this function is more often referred to as an **Ingress**. In short, Load Balancer and Ingress play the same role. diff --git a/content/rancher/v2.x/en/v1.6-migration/migration-tools-ref/_index.md b/content/rancher/v2.x/en/v1.6-migration/migration-tools-ref/_index.md index ebda029781c..1c1c060e730 100644 --- a/content/rancher/v2.x/en/v1.6-migration/migration-tools-ref/_index.md +++ b/content/rancher/v2.x/en/v1.6-migration/migration-tools-ref/_index.md @@ -3,7 +3,7 @@ title: Migration Tools CLI Reference weight: 100 --- -The migration-tools CLI includes multiple commands and options to assist your migration from v1.6 to v2.0. This reference to find out what commands and options are available when using . +The migration-tools CLI includes multiple commands and options to assist your migration from Rancher v1.6 to Rancher v2.x. ## Download @@ -15,9 +15,9 @@ The migration-tools CLI for your platform can be downloaded from our [GitHub rel migration-tools [global options] command [command options] [arguments...] ``` -## Global Options +## Migration Tools Global Options -The migration-tools CLI includes a handful of options that can be used regardless of which commands you are using. These options are not required to run the tool. Rather, they're useful for troubleshooting. +The migration-tools CLI includes a handful of global options. | Global Option | Description | | ----------------- | -------------------------------------------- | @@ -26,22 +26,60 @@ The migration-tools CLI includes a handful of options that can be used regardles | `--help`, `-h` | Displays a list of all commands available. | | `--version`, `-v` | Prints the version of migration-tools CLI in use.| - ## Commands and Command Options -This section contains reference material for commands and options available for the migration-tools CLI. +### Migration-Tools Export Reference -Command | Options | Required? | Description ---------|---------|-------------|----- -`export`| | N/A | Exports Compose files for every Stack running in a Cattle environment in Rancher v1.6. - |`--url ` | ✓ | Rancher API endpoint URL (``). - |`--access-key ` | ✓ | Rancher API access key. Using an admin [API key]({{< baseurl >}}/rancherv2.x/en/user-settings/api-keys) exports stacks from all cattle environments (``). - |`--secret-key ` | ✓ | Rancher [API secret key]({{< baseurl >}}/rancherv2.x/en/user-settings/api-keys) (``). - |`--export-dir ` | | Base directory that Compose files export to under sub-directories created for each environment/stack (default: `Export`). - |`--all`, `--a` | | Export all stacks. Using this flag exports any stack in a state of inactive, stopped, or removing. - |`--system`, `--s` | | Export system and infrastructure stacks. -`parse` | | N/A | Parse Docker Compose and Rancher Compose files to get Kubernetes manifests. - |`--docker-file ` | | Parses Docker Compose file to output Kubernetes manifest (default: `docker-compose.yml`) - |`--output-file ` | | Name of file that outputs listing checks and advice for conversion (default: `output.txt`). - |`--rancher-file ` | | Parses Rancher Compose file to output Kubernetes manifest (default: `rancher-compose.yml`) -`help`, `h` | | N/A | Shows a list of options available for use with preceding command. +The `migration-tools export` command exports all stacks from your Rancher v1.6 server into Compose files. + +#### Options + +| Option | Required? | Description| +| --- | --- |--- | +|`--url ` | ✓ | Rancher API endpoint URL (``). | +|`--access-key ` | ✓ | Rancher API access key. Using an account API key exports all stacks from all cattle environments (``). | +|`--secret-key ` | ✓ | Rancher API secret key associated with the access key. (``). | +|`--export-dir ` | | Base directory that Compose files export to under sub-directories created for each environment/stack (default: `Export`). | +|`--all`, `--a` | | Export all stacks. Using this flag exports any stack in a state of inactive, stopped, or removing. | +|`--system`, `--s` | | Export system and infrastructure stacks. | + + +#### Usage + +Execute the following command, replacing each placeholder with your values. The access key and secret key are Account API keys, which will allow you to export from all Cattle environments. + +``` +migration-tools export --url --access-key --secret-key --export-dir +``` + +**Result:** The migration-tools CLI exports Compose files for each stack in every Cattle environments in the `--export-dir` directory. If you omitted this option, the files are saved to your current directory. + +### Migration-Tools Parse Reference + +The `migration-tools parse` command parses the Compose files for a stack and uses [Kompose](https://github.com/kubernetes/kompose) to generate an equivalent Kubernetes YAML. It also outputs an `output.txt` file, which lists all the constructs that will need manual intervention in order to be converted to Kubernetes. + +#### Options + +| Option | Required? | Description +| ---|---|--- +|`--docker-file ` | | Parses Docker Compose file to output Kubernetes manifest (default: `docker-compose.yml`) +|`--output-file ` | | Name of file that outputs listing checks and advice for conversion (default: `output.txt`). +|`--rancher-file ` | | Parses Rancher Compose file to output Kubernetes manifest (default: `rancher-compose.yml`) + +#### Subcommands + +| Subcommand | Description | +| ---|---| +| `help`, `h` | Shows a list of options available for use with preceding command. | + +#### Usage + +Execute the following command, replacing each placeholder with the absolute path to your Stack's Compose files. For each stack, you'll have to re-run the command for each pair of Compose files that was exported. + +``` +migration-tools parse --docker-file --rancher-file +``` + +>**Note:** If you omit the `--docker-file` and `--rancher-file` options from your command, the migration-tools CLI checks its home directory for these Compose files. + +**Result:** The migration-tools CLI parses your Compose files and outputs Kubernetes YAML specs as well as an `output.txt` file. For each service in the stack, a YAML spec file is created and named the same as your service. The `output.txt` file lists all constructs for each service in `docker-compose.yml` that requires special handling to be successfully migrated to Rancher 2.x. Each construct links to the relevant blog articles on how to implement it in Rancher 2.x.