diff --git a/content/rancher/v2.x/en/catalog/_index.md b/content/rancher/v2.x/en/catalog/_index.md index ff9815d2d35..ead9a0c0e3e 100644 --- a/content/rancher/v2.x/en/catalog/_index.md +++ b/content/rancher/v2.x/en/catalog/_index.md @@ -1,19 +1,17 @@ --- -title: Catalogs and Charts +title: Catalogs and Apps weight: 4000 aliases: - /rancher/v2.x/en/concepts/global-configuration/catalog/ - /rancher/v2.x/en/concepts/catalogs/ - /rancher/v2.x/en/tasks/global-configuration/catalog/ - - /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/ - - /rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs/ --- -Rancher provides a catalog of charts that make it easy to repeatedly deploy any applications. +## Catalogs -_Catalogs_ are GitHub repositories or Helm Chart Repository filled with applications that are ready-made for deployment. Applications are bundled in objects called _charts_. +Rancher provides the ability to use a catalog of Helm charts that make it easy to repeatedly deploy applications. -_Charts_ are a packaging format popularized by [Helm](https://docs.helm.sh/). Think of them as templates for deployments. Per Helm, charts are: +_Catalogs_ are GitHub repositories or Helm Chart repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called _Helm charts_. >A collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. @@ -121,17 +119,21 @@ After you've either enabled the built-in catalogs or added your own custom catal **Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's: -- **Workloads** view -- **Apps** view (In versions prior to v2.2.0, this is the **Catalog Apps** view). +By creating a customized repository with added files, Rancher improves on Helm repositories and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience. -## Deleting Catalog Application Deployments +### Catalog Scope -As a safeguard to prevent you from unintentionally deleting other catalog applications that share a namespace, deleting catalog applications themselves does not delete the namespace they're assigned to. Therefore, when you want to delete a deployed catalog application, assuming that it's the only app in its namespace, delete the namespace rather than the catalog app itself. Deleting the namespace deletes both the namespace and the catalog app, whereas deleting the catalog app only deletes the app but not the namespace. +Within Rancher, you can manage catalogs at three different scopes. Global catalogs is shared across all clusters and project. There are some use cases where you might not want to share catalogs across between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects. -1. From the **Global** view, open the project that contains the catalog application that you want to delete. +Scope | Description | Available As of | +--- | --- | --- | +Global | All clusters and all projects can access the Helm charts in this catalog | v2.0.0 | +Cluster | All projects in the specific cluster can access the Helm charts in this catalog | v2.2.0 | +Project | This specific cluster can access the Helm charts in this catalog | v2.2.0 | -1. From the main menu, choose **Namespaces**. +## Apps -1. Find the namespace running your catalog app. Select it and click **Delete**. +In Rancher, applications are deployed from the templates in a catalog. Rancher supports two types of applications: -**Result:** The catalog application deployment and its namespace are deleted. +* [Multi-cluster applications]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster/) +* [Applications deployed in a specific Project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps) diff --git a/content/rancher/v2.x/en/catalog/apps/_index.md b/content/rancher/v2.x/en/catalog/apps/_index.md new file mode 100644 index 00000000000..8777437f36e --- /dev/null +++ b/content/rancher/v2.x/en/catalog/apps/_index.md @@ -0,0 +1,125 @@ +--- +title: Apps in a Project +weight: 5005 +--- + +Within a project, when you want to deploy applications from catalogs, the applications available in your project will be based on the [scope of the catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/#catalog-scope). + +## Launching Catalog Applications + +After you've either enabled the [built-in global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/) or [added your own custom catalog]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/adding), you can start launching catalog applications. + +1. From the **Global** view, navigate to your project that you want to start deploying applications. + +2. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**. + +3. Find the application that you want to launch, and then click **View Details**. + +4. (Optional) Review the detailed descriptions, which are derived from the Helm chart readme. + +5. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application. + + * If you would like to change the **Namespace**, click **Customize** and change the name of the namespace. + * If you want to use a different namespace that already exists, click **Customize**, and then click **Use an existing namespace**. Choose a namespace from the list. + +6. Select a **Template Version**. + +7. Complete the rest of the **Configuration Options**. Rancher handles how to [customize your configuration options](#configuration-options) depending on whether or not the custom catalog includes the `questions.yml` file. + +8. Review the files in the **Preview** section. When you're satisfied, click **Launch**. + +**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's: + +- **Workloads** view +- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view. + +### Configuration Options + +For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set), as Rancher passes them as ``--set` flags to Helm. + +> For example, when entering an answer that includes two values separated by a comma (i.e. `abc, bcd`), it is reuired to wrap the values with double quotes (i.e., ``"abc, bcd"``). + +{{% tabs %}} +{{% tab "UI" %}} + +#### Using a `questions.yml` file + +If the Helm chart that you are deploying contains a `questions.yml` file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions. + +#### Key Value Pairs for Native Helm Charts + +For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values. + +{{% /tab %}} +{{% tab "Editing YAML Files" %}} + +_Available as of v2.1.0_ + +If you do not want to input answers using the UI, you can choose the **Edit as YAML** option. + +With this example YAML: + +```YAML +outer: + inner: value +servers: +- port: 80 + host: example +``` + +#### Kev Value Pairs + +You can have a YAML file that translates these fields to match how to [format custom values so that it can be used with `--set`](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set). + +These values would be translated to: + +``` +outer.inner=value +servers[0].port=80 +servers[0].host=example +``` + +#### YAML files + +_Available as of v2.2.0_ + +You can directly paste that YAML formatted structure into the YAML editor. By allowing custom values to be set using a YAML formatted structure, Rancher has the ability to easily customize for more complicated input values (e.g. multi-lines, array and JSON objects). +{{% /tab %}} +{{% /tabs %}} + +## Upgrading/Rolling Back Catalog applications + +After an application is deployed, you can easily upgrade or rollback to a different template version. + +1. From the **Global** view, navigate to the project that contains the catalog application that you want to upgrade. + +1. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**. + +3. Find the application that you want to upgrade/rollback, and then click the Ellipsis to find **Upgrade**/**Rollback**. + +4. Select the **Template Version** that you want to deploy. + +5. (Optional) Update your **Configuration Options**. + +6. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for **Delete and recreate resources if needed during the upgrade**. + + > In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the upgrade/rollback. + +7. Review the files in the **Preview** section. When you're satisfied, click **Launch**. + +**Result**: Your application is updated. You can view the application status from the project's: + +- **Workloads** view +- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view. + +## Deleting Catalog Application Deployments + +As a safeguard to prevent you from unintentionally deleting other catalog applications that share a namespace, deleting catalog applications themselves does not delete the namespace they're assigned to. Therefore, when you want to delete a deployed catalog application, assuming that it's the only app in its namespace, delete the namespace rather than the catalog app itself. Deleting the namespace deletes both the namespace and the catalog app, whereas deleting the catalog app only deletes the app but not the namespace. + +1. From the **Global** view, navigate to the project that contains the catalog application that you want to delete. + +1. From the main menu, choose **Namespaces**. + +1. Find the namespace running your catalog app. Select it and click **Delete**. + +**Result:** The catalog application deployment and its namespace are deleted. diff --git a/content/rancher/v2.x/en/catalog/built-in/_index.md b/content/rancher/v2.x/en/catalog/built-in/_index.md new file mode 100644 index 00000000000..f2fc3258561 --- /dev/null +++ b/content/rancher/v2.x/en/catalog/built-in/_index.md @@ -0,0 +1,35 @@ +--- +title: Built-in Global Catalogs +weight: 4000 +aliases: + - /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/ +--- + +There are default [global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/#global-catalogs) packaged as part of Rancher. + +## Managing Built-in Global Catalogs + +>**Prerequisites:** In order to manage the [built-in catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/) or [manage global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom-adding/#adding-global-catalogs), you need _one_ of the following permissions: +> +>- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) +>- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned. + +1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar. + +2. Toggle the default catalogs that you want use to a setting of **Enabled**. + + - **Library** + + The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. In Rancher 2.x, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future. + + This catalog features Rancher Charts, which include some [notable advantages]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts. + + - **Helm Stable** + + This catalog, , which is maintained by the Kubernetes community, includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md). This catalog features the largest pool of apps. + + - **Helm Incubator** + + Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**. + + **Result**: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Apps** from the main navigation bar. In versions prior to v2.2.0, within a project, you can select **Catalog Apps** from the main navigation bar. diff --git a/content/rancher/v2.x/en/catalog/chart-custom-values/_index.md b/content/rancher/v2.x/en/catalog/chart-custom-values/_index.md deleted file mode 100644 index 5b0f3acf253..00000000000 --- a/content/rancher/v2.x/en/catalog/chart-custom-values/_index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Custom values.yaml for Catalog Apps -weight: 4035 -aliases: - - /rancher/v2.x/en/tasks/global-configuration/catalog/custom-values-for-apps/ ---- - -For both Rancher or custom catalog apps, the user can override the default values in the `Answers` section. - -For example, setting custom values of the default values.yaml - -```YAML -outer: - inner: value -servers: -- port: 80 - host: example -``` - -need to be translated into `outer.inner=value`, `servers[0].port=80` and `servers[0].host=example` respectively in the Answers section -(Read more about [Format of Custom Values Using `--Set`](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set)). - - -or through `Edit as YAML` view: - -
app-readme.md (left) vs. Helm Chart without (right)questions.yml (left) vs. Helm Chart without (right)- categories: - - Blog - - CMS - questions: - - variable: persistence.enabled - default: "false" - description: "Enable persistent volume for WordPress" - type: boolean - required: true - label: WordPress Persistent Volume Enabled - show_subquestion_if: true - group: "WordPress Settings" - subquestions: - - variable: persistence.size - default: "10Gi" - description: "WordPress Persistent Volume Size" - type: string - label: WordPress Volume Size - - variable: persistence.storageClass - default: "" - description: "If undefined or null, uses the default StorageClass. Default to null" - type: storageclass - label: Default StorageClass for WordPress -- -4. Check the customized chart into your GitHub repo. - -**Result:** Your custom chart is added to the repo. Your Rancher Server will replicate the chart within a few minutes. +3. For `Username`, provide the Git generated OAuth token. For `Password`, enter `x-oauth-basic`. diff --git a/content/rancher/v2.x/en/catalog/custom/adding/_index.md b/content/rancher/v2.x/en/catalog/custom/adding/_index.md new file mode 100644 index 00000000000..195a81e87b1 --- /dev/null +++ b/content/rancher/v2.x/en/catalog/custom/adding/_index.md @@ -0,0 +1,58 @@ +--- +title: Adding Custom Catalogs +weight: 4005 +aliases: + - /rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs/ +--- + +[Custom catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom/) can be added into Rancher at any [scope of Rancher]({{< baseurl >}}/rancher/v2.x/en/catalog/#catalog-scope). + +## Adding Global Catalogs + +>**Prerequisites:** In order to manage the [built-in catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/built-in/) or [manage global catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom-adding/#adding-global-catalogs), you need _one_ of the following permissions: +> +>- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) +>- [Custom Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned. + + 1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar. + 2. Click **Add Catalog**. + 3. Complete the form and click **Create**. + + **Result**: Your custom global catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [multi-cluster apps]({{< baseurl >}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or [applications in any project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/) from this catalog. + +## Adding Cluster Catalogs + +_Available as of v2.2.0_ + +>**Prerequisites:** In order to [manage cluster scoped catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom-adding/#adding-cluster-catalogs), you need _one_ of the following permissions: +> +>- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) +>- [Cluster Owner Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) +>- [Custom Cluster Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Cluster Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-role-reference) role assigned. + +1. From the **Global** view, navigate to your cluster that you want to start adding custom catalogs. +2. Choose the **Tools > Catalogs** in the navigation bar. +2. Click **Add Catalog**. +3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Cluster** scope, it is defaulted to `Cluster`. +5. Click **Create**. + +**Result**: Your custom cluster catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in any project in that cluster]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/) from this catalog. + +## Adding Project Level Catalogs + +_Available as of v2.2.0_ + +>**Prerequisites:** In order to [manage project scoped catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/custom-adding/#adding-project-catalogs), you need _one_ of the following permissions: +> +>- [Administrator Global Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) +>- [Cluster Owner Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) +>- [Project Owner Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) +>- [Custom Project Permissions]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Project Catalogs]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) role assigned. + +1. From the **Global** view, navigate to your project that you want to start adding custom catalogs. +2. Choose the **Tools > Catalogs** in the navigation bar. +2. Click **Add Catalog**. +3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Project** scope, it is defaulted to `Cluster`. +5. Click **Create**. + +**Result**: Your custom project catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in that project]({{< baseurl >}}/rancher/v2.x/en/catalog/apps/) from this catalog. diff --git a/content/rancher/v2.x/en/catalog/custom/creating/_index.md b/content/rancher/v2.x/en/catalog/custom/creating/_index.md new file mode 100644 index 00000000000..582cdbce5c0 --- /dev/null +++ b/content/rancher/v2.x/en/catalog/custom/creating/_index.md @@ -0,0 +1,169 @@ +--- +title: Creating Custom Catalogs +weight: 4000 +aliases: + - /rancher/v2.x/en/tasks/global-configuration/catalog/customizing-charts/ +--- + +Rancher's catalog service requires any custom catalogs to be structured in a specific format for the catalog service to be able to leverage it in Rancher. + +## Chart Types + +Rancher supports two different types of charts: + +- **Helm Charts** + + Native Helm charts include an application along with other software required to run it. When deploying native Helm charts, you'll learn the chart's parameters and then configure them using **Answers**, which are sets of key value pairs. + + The Helm Stable and Helm Incubators are populated with native Helm charts. However, you can also use native Helm charts in Custom catalogs (although we recommend Rancher Charts). + +- **Rancher Charts** + + Rancher charts mirror native helm charts, although they add two files that enhance user experience: `app-readme.md` and `questions.yaml`. Read more about them in [Rancher Chart Additional Files](#rancher-chart-additional-files). + + Advantages of Rancher charts include: + + - **Enhanced Revision Tracking** + + While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart. + + - **Streamlined Application Launch** + + Rancher charts add simplified chart descriptions and configuration forms to make catalog application deployment easy. Rancher users need not read through the entire list of Helm variables to understand how to launch an application. + + - **Application Resource Management** + + Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application. + +## Chart Directory Structure + +The following table demonstrates the directory structure for a chart, which can be found in a chart directory: `charts/
app-readme.md (left) vs. Helm Chart without (right)questions.yml (left) vs. Helm Chart without (right)+ categories: + - Blog + - CMS + questions: + - variable: persistence.enabled + default: "false" + description: "Enable persistent volume for WordPress" + type: boolean + required: true + label: WordPress Persistent Volume Enabled + show_subquestion_if: true + group: "WordPress Settings" + subquestions: + - variable: persistence.size + default: "10Gi" + description: "WordPress Persistent Volume Size" + type: string + label: WordPress Volume Size + - variable: persistence.storageClass + default: "" + description: "If undefined or null, uses the default StorageClass. Default to null" + type: storageclass + label: Default StorageClass for WordPress ++ +4. Check the customized chart into your GitHub repo. + +**Result:** Your custom chart is added to the repo. Your Rancher Server will replicate the chart within a few minutes. diff --git a/content/rancher/v2.x/en/catalog/force-upgrade/_index.md b/content/rancher/v2.x/en/catalog/force-upgrade/_index.md deleted file mode 100644 index 7e3597297b6..00000000000 --- a/content/rancher/v2.x/en/catalog/force-upgrade/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Force Upgrade Catalog Apps -weight: 4040 -aliases: - - /rancher/v2.x/en/tasks/global-configuration/catalog/force-upgrade-catalog-apps/ ---- - -_Available as of v2.2.0_ - -In Kubernetes, some fields are designed to be immutable or cannot be updated directly. Force upgrade will force Rancher catalog apps to delete and recreate resources if needed during the upgrade. - - -### How to Force-upgrade Catalog Apps - -For both upgrade and rollback, you can select the `Delete and recreate resources if needed during the upgrade` checkbox at the bottom of the catalog app details page to force-upgrade the app. - - diff --git a/content/rancher/v2.x/en/apps/multi-cluster-apps/_index.md b/content/rancher/v2.x/en/catalog/multi-cluster-apps/_index.md similarity index 97% rename from content/rancher/v2.x/en/apps/multi-cluster-apps/_index.md rename to content/rancher/v2.x/en/catalog/multi-cluster-apps/_index.md index 85b6c4f8477..f4e646b2bee 100644 --- a/content/rancher/v2.x/en/apps/multi-cluster-apps/_index.md +++ b/content/rancher/v2.x/en/catalog/multi-cluster-apps/_index.md @@ -4,7 +4,7 @@ weight: 5000 --- _Note: Available as of v2.2.0_ -In use cases where you need to deploy copies of the same workload to multiple clusters or projects, deploy it using a multi-cluster app. A _multi-cluster app_ is an app installed using a Helm Chart across multiple clusters. +In use cases where you need to deploy copies of the same workload to multiple clusters or projects, deploy it using a multi-cluster app. A _multi-cluster app_ is an app installed using a Helm Chart across multiple clusters. Multi-Cluster Apps are beneficial because they reduce the repetition of deploying individual workloads to each target. They also reduce the likelihood of user error during workload configuration, as you only have to configure a single object rather than a unique object for each target. But you still have the option of configuring workloads of an app differently for certain targets, through Answer Overrides. Additionally, because multi-cluster apps are a single object, they simplify routine maintenance. For example, rather than upgrading several apps, you can upgrade the multi-cluster app, which then propagates the upgrade action to the app in each target project. @@ -13,10 +13,10 @@ You can deploy multi-cluster apps using a template from any global level catalog ## Multi-Cluster App Installation -1. From the Global View, go to **Apps** -> **Multi-Cluster Apps**. -2. This page lists all multi-cluster apps you have access to. +1. From the Global View, go to **Apps** -> **Multi-Cluster Apps**. +2. This page lists all multi-cluster apps you have access to. 3. Click on **Launch** and select an application template. -4. You'll find a lot of similarities between this and the Catalog App Launch page. Over here, you get to configure your multi- cluster app, and all the apps it launches in your target projects. +4. You'll find a lot of similarities between this and the Catalog App Launch page. Over here, you get to configure your multi- cluster app, and all the apps it launches in your target projects. You can categorize these configuration details in two parts. ### Configure your Multi-Cluster App @@ -42,26 +42,26 @@ You can choose from these three access-types while adding a user to your multi-c 3. Roles Along with this, they can also manage the configuration of the apps launched by the multi-cluster app. They can do so by modifying the following fields 1. Version of the application template - 2. Answers passed to certain target projects or their clusters, by using Answer Overrides - + 2. Answers passed to certain target projects or their clusters, by using Answer Overrides + So in short, owners can alter the multi-cluster app, and the corresponding apps, or delete the multi-cluster app. They can manage/remove apps in target projects by modifying the targets list, without expliciltly being members of these projects. Hence, make sure you add only trusted users with the access-type `owner`. - + - **Member** User added with access-type member, has permissions to modify the configuration of apps launched by the multi-cluster app across all target projects. They can do so by updating the following fields 1. Version of the application template 2. Answers passed to certain target projects or their clusters, by using Answer Overrides - + Users added with access type `Member` can modify your underlying apps without explicitly being part of the projects these apps are launched in. Hence be sure to added trusted users with `Member` access type. - **Read-only** - Users given read-only access can only list/get the multi-cluster apps, and can't modify it. + Users given read-only access can only list/get the multi-cluster apps, and can't modify it. **NOTE** Please make sure you share your multi-cluster app with only trusted users as `Owner` or `Member`. - **Roles** - - When you launch a regular Catalog App through Rancher, your permissions get used for creation of all workloads/resources that the app needs. You are marked as the creator of this app. A change in your permissions in Rancher, will affect your ability to further manage this app. - - Multi-cluster app on the other hand launches these catalog apps for you in the target projects. But we don't want the multi-cluster app creator to be added as the underlying apps' creator. The reason being, a change in your permissions could affect how all these apps will get managed. If you accidentally get removed from one of the target projects, you can no longer control the app in that project. + - When you launch a regular Catalog App through Rancher, your permissions get used for creation of all workloads/resources that the app needs. You are marked as the creator of this app. A change in your permissions in Rancher, will affect your ability to further manage this app. + - Multi-cluster app on the other hand launches these catalog apps for you in the target projects. But we don't want the multi-cluster app creator to be added as the underlying apps' creator. The reason being, a change in your permissions could affect how all these apps will get managed. If you accidentally get removed from one of the target projects, you can no longer control the app in that project. Hence we create a behind-the-scenes system user and assign it as the creator of all underyling apps of a multi-cluster app. You can pass permissions to this system user through `Roles`. - **Roles accepted are based on your permissions** @@ -71,7 +71,7 @@ Please make sure you share your multi-cluster app with only trusted users as `Ow - For example if you select the Project permission, you need to have the role "project-member" in all target projects. But these exact match checks are relaxed for global admins, owners of the target projects, and their clusters (users with role "project-owner" in targets or "cluster-owner" in clusters of these target projects). - If instead you select the Cluster permissions, you need to be the cluster-owner of the target project's clusters (This too is relaxed for the global admin). - If you are a cluster-owner of the clusters your target projects belong to, you can pass "Project" or "Cluster" roles, without explicitly being a member of the clusters' projects. - - If you are a project-owner, or project-member of your target projects, you can pass the "Project" role only. + - If you are a project-owner, or project-member of your target projects, you can pass the "Project" role only. - If you don't have any of these roles, it means you don't have enough permissions in the selected target projects to create apps. So you cannot assign anyone else these roles either. - You can just start your multi-cluster app with the Project permissions selected by default. This corresponds to the `project-member` role, which encompassess all permissions required for managing apps and most workloads. This also does a check of your membership in that project. If you are an owner or a member of the target projects, your multi-cluster app creation will go through. But if you don't have any of these exact roles in the targets, then you won't be allowed to create a multi-cluster app with these targets. - There are some apps like grafana or datadog, that require access to certain cluster-scoped resources, which the "project-member" role cannot provide. In that case, please select the Cluster permissions. Even if you launch your multi-cluster app with the Project role, you can later upgrade to use the Cluster permissions. @@ -111,4 +111,3 @@ After deploying a multi-cluster app, you need to maintain it using the catalog f - **Rollback** In the event that an upgrade causes issues for one or more of your targets, you can roll the application back to the prior version. We store up to 10 revisions of your multi-cluster app from which you can choose one. Rolling back a multi-cluster app reverts it for _all_ target clusters and projects, not just those targets affected by the upgrade issue. - diff --git a/content/rancher/v2.x/en/catalog/private/_index.md b/content/rancher/v2.x/en/catalog/private/_index.md deleted file mode 100644 index 2575ad8fc47..00000000000 --- a/content/rancher/v2.x/en/catalog/private/_index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Add Private Catalogs -weight: 4030 -aliases: - - /rancher/v2.x/en/tasks/global-configuration/catalog/add-private-catalogs/ ---- - -## Add Private Git/Helm Chart Repositories -_Available as of v2.2.0_ - -You can add private catalog repositories based on Helm and Git. - - - -### Add Private Git/Helm Chart Repository using username and password: - -1. From the `Global -> Catalogs` page, click **Add Catalog** to add your custom private chart repository: - - | Variable | Description | - | -------------------- | ------------- | - | Name | Custom catalog name. | - | Catalog URL | The URL of your custom chart repository. | - | Use Private Catalog | Select it to use private catalog. | - | Username | Your Git/Helm username. | - | Password | Your Git/Helm password. | - | Branch | Git branch name. Ignored if it is a Helm repository. | - - -**Result**: Your custom catalog is added to the Rancher with `Active` state once it completes synchronization. - -### Add Private Git Chart Repository using OAuth token: - -1. Create an [OAuth token](https://github.com/settings/tokens) -with `repo` permission selected, and click **Generate token**. - -  - - -2. From the `Global -> Catalogs` page, click **Add Catalog** to add your custom private chart repository: - - | Variable | Description | - | -------------------- | ------------- | - | Name | Custom catalog name. | - | Catalog URL | The URL of your custom chart repository. | - | Use Private Catalog | Select it to use private catalog. | - | Username | Your Git generated OAuth token. | - | Password | Enter `x-oauth-basic`. read [using Git over HTTPS and OAuth](https://github.blog/2012-09-21-easier-builds-and-deployments-using-git-over-https-and-oauth/) for more details. | - | Branch | Your Git branch name, default to master. | - - -**Result**: Your custom catalog is added to the Rancher with `Active` state once it completes synchronization. diff --git a/content/rancher/v2.x/en/catalog/project-cluster-catalog/_index.md b/content/rancher/v2.x/en/catalog/project-cluster-catalog/_index.md deleted file mode 100644 index 25ad3b79751..00000000000 --- a/content/rancher/v2.x/en/catalog/project-cluster-catalog/_index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Cluster and Project Level Catalogs -weight: 4020 ---- -_Note: Available as of v2.2.0_ - -### Cluster and Project Level Catalogs - -The catalog added at the global level is shared with all clusters and projects. This means all users have equal access to the application templates (charts) from these global catalogs. -Some use cases require cluster level isolation between application templates from catalogs. For instance, when you have clusters dedicated to different teams (dev, QA, prod) or different customers. -Rancher 2.2 can address this need by letting you add catalogs at the cluster level. -A similar need for isolation between catalogs might arise at the project-level too. For example, if different teams are working in the same cluster but in separate projects and want to make some application templates available only for certain teams. For this, Rancher 2.2 also lets you add a catalog at the project level. - -### Adding Cluster Level Catalogs - -Only cluster owners are allowed to add/update/remove catalogs at the cluster level. All other cluster members can view and use templates from them. - -1. From the **Global** view, navigate to your cluster. -2. From the **Tools** dropdown, select **Catalogs**. -2. Click **Add Catalog**. -3. The form presented will be very similar to the one shown while adding a global level catalog -4. Along with the `Name`, `URL`, `Branch`, you also get to select `Scope` of the catalog. It is defaulted to `Cluster` when you're adding a catalog at the cluster level. -5. Fill out the form and click on **Create** - -### Adding Project Level Catalogs - -Only project owners are allowed to add/update/remove catalogs at the project level. All other project members can view and use templates from them. - -1. From the **Global** view, navigate to your project. -2. Choose **Apps** from the main menu -2. Click **Manage Catalogs**. -3. The form presented will be very similar to the one shown while adding a global and cluster level catalog -4. Along with the `Name`, `URL`, `Branch`, you also get to select `Scope` of the catalog. It is defaulted to `Project` when you're adding a catalog at the project level. -5. Fill out the form and click on **Create** - -### Access to Catalogs and Templates - -Global catalog templates are accessible across all the clusters and projects. -Cluster level catalog templates are accessible only within the cluster they belong to. -Project level catalog templates are accessible only within the project they belong to. diff --git a/static/img/rancher/catalog/add-git-token.png b/static/img/rancher/catalog/add-git-token.png deleted file mode 100644 index 25282c43980..00000000000 Binary files a/static/img/rancher/catalog/add-git-token.png and /dev/null differ diff --git a/static/img/rancher/catalog/add-private-catalog.png b/static/img/rancher/catalog/add-private-catalog.png deleted file mode 100644 index 0f34f963f4d..00000000000 Binary files a/static/img/rancher/catalog/add-private-catalog.png and /dev/null differ diff --git a/static/img/rancher/catalog/custom-values-yaml-long.png b/static/img/rancher/catalog/custom-values-yaml-long.png deleted file mode 100644 index 0d72a7b21be..00000000000 Binary files a/static/img/rancher/catalog/custom-values-yaml-long.png and /dev/null differ diff --git a/static/img/rancher/catalog/custom-values-yaml.png b/static/img/rancher/catalog/custom-values-yaml.png deleted file mode 100644 index c43c3399092..00000000000 Binary files a/static/img/rancher/catalog/custom-values-yaml.png and /dev/null differ diff --git a/static/img/rancher/catalog/dot-custom-values-form.png b/static/img/rancher/catalog/dot-custom-values-form.png deleted file mode 100644 index 6fd4711cc80..00000000000 Binary files a/static/img/rancher/catalog/dot-custom-values-form.png and /dev/null differ diff --git a/static/img/rancher/catalog/dot-custom-values.png b/static/img/rancher/catalog/dot-custom-values.png deleted file mode 100644 index 9ac225972e4..00000000000 Binary files a/static/img/rancher/catalog/dot-custom-values.png and /dev/null differ diff --git a/static/img/rancher/catalog/force-upgrade.png b/static/img/rancher/catalog/force-upgrade.png deleted file mode 100644 index cfbfc6a9d29..00000000000 Binary files a/static/img/rancher/catalog/force-upgrade.png and /dev/null differ