Skip to content
This repository has been archived by the owner on Jul 4, 2024. It is now read-only.

Commit

Permalink
Update Compass installation document (#1481)
Browse files Browse the repository at this point in the history
  • Loading branch information
@klaudiagrz
klaudiagrz authored Jul 3, 2020
1 parent ffcc2c6 commit f2eef91
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 95 deletions.
35 changes: 5 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,44 +26,17 @@ For more information about the Compass architecture, technical details, and comp

## Installation

### Enable Compass in Kyma
Install Compass locally or on a cluster. See the [installation document](https://github.com/kyma-incubator/compass/blob/master/docs/compass/04-01-installation.md) for details.

Read [this](https://github.com/kyma-incubator/compass/blob/master/docs/compass/04-01-installation.md) document to learn about different modes in which you can enable Compass in Kyma.

### Chart installation
## Testing

If you already have a running Kyma instance in at least 1.6 version, with created Secrets and Tiller client certificates, you can install the Compass Helm chart using this command:
```bash
helm install --name "compass" ./chart/compass --tls
```

For local installation, specify additional parameters:
```bash
helm install --set=global.isLocalEnv=true --set=global.minikubeIP=$(eval minikube ip) --name "compass" ./chart/compass --tls
```

### Local installation with Kyma

To install Compass along with the minimal Kyma installation from the `master` branch, run this script:
```bash
./installation/cmd/run.sh
```

You can also specify Kyma version, such as 1.6 or newer:
```bash
./installation/cmd/run.sh {version}
```

### Testing

Compass, as a part of Kyma, uses [Octopus](https://github.com/kyma-incubator/octopus/blob/master/README.md) for testing. To run the Compass tests, run:
Compass uses [Octopus](https://github.com/kyma-incubator/octopus/blob/master/README.md) for testing both locally and on a cluster. To run the Compass tests, use this script:

```bash
./installation/scripts/testing.sh
```

Read [this](https://kyma-project.io/docs/root/kyma#details-testing-kyma) document to learn more about testing in Kyma.

## Usage

Currently, the Compass Gateway is accessible under three different hosts secured with different authentication methods:
Expand All @@ -73,3 +46,5 @@ Currently, the Compass Gateway is accessible under three different hosts secured
- `https://compass-gateway-auth-oauth.{domain}` - secured with OAuth 2.0 access token issued by [Hydra](https://kyma-project.io/docs/components/security/#details-o-auth2-and-open-id-connect-server)

You can access Director GraphQL API under the `/director/graphql` endpoint, and Connector GraphQL API under `/connector/graphql`.

To access Connectivity Adapter, use the `https://adapter-gateway.{DOMAIN}` host secured with one-time tokens or `https://adapter-gateway-mtls.{DOMAIN}` secured with client certificates (mTLS).
120 changes: 55 additions & 65 deletions docs/compass/04-01-installation.md
View file
Original file line number Diff line number Diff line change
@@ -1,78 +1,68 @@
# Enable Compass in Kyma
# Compass installation

To enable Compass in Kyma, follow the instructions for the [custom component installation](https://kyma-project.io/docs/master/root/kyma#configuration-custom-component-installation) and enable the `compass` and `compass-runtime-agent` modules. You can also [install Kyma on a cluster](https://kyma-project.io/docs/master/root/kyma#installation-install-kyma-on-a-cluster) with the ready-to-use configurations for different modes. There are two modes in which you can enable Compass in Kyma: default Kyma installation and Compass as a Central Management Plane.
You can install Compass both on a cluster and on your local machine.

## Default Kyma installation
## Cluster installation

![Kyma mode1](./assets/kyma-mode1.svg)
Follow these steps to install Compass on a cluster:

This is a single-tenant mode which provides the complete cluster Kyma installation with all components, including Compass and the Runtime Agent. In this mode, the Runtime Agent is already connected to Compass. Using this mode, you can register external Applications in Kyma. To enable it, follow the cluster Kyma installation using the [`installer-cr-cluster-with-compass.yaml.tpl`](https://github.com/kyma-project/kyma/blob/master/installation/resources/installer-cr-cluster-with-compass.yaml.tpl) configuration file. The default [legacy mode](#architecture-application-connector-components-application-operator) used in Kyma does not support integration with Compass. For that reason, before you start the installation, apply the following ConfigMap which disables components used in the legacy mode, such as the Application Registry and the Connector Service:
1. [Install Kyma with the Runtime Agent.](https://kyma-project.io/docs/master/components/runtime-agent#installation-installation)
2. Apply the following ConfigMap before you proceed with the Compass installation:

```yaml
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
name: disable-legacy-connectivity-override
namespace: kyma-installer
labels:
installer: overrides
kyma-project.io/installation: ""
data:
global.disableLegacyConnectivity: "true"
EOF
```

## Compass as a Central Management Plane

This is a multi-cluster mode in which you need one cluster with Compass and at least one cluster with Kyma Runtime, which you can connect and manage using Compass. This mode allows you to integrate your Runtimes with Applications and manage them in one central place.

![Kyma mode2](./assets/kyma-mode2.svg)
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: compass-overrides
namespace: compass-installer
labels:
installer: overrides
component: compass
kyma-project.io/installation: ""
data:
# The name of the currently used gateway
global.istio.gateway.name: "kyma-gateway"
# The Namespace of the currently used gateway
global.istio.gateway.namespace: "kyma-system"
global.connector.secrets.ca.name: "connector-service-app-ca"
# The Namespace with a Secret that contains a certificate for the Connector Service
global.connector.secrets.ca.namespace: "kyma-integration"
# The parameter that enables the Compass gateway, as the default Kyma gateway is disabled in this installation mode
gateway.gateway.enabled: "false"
global.disableLegacyConnectivity: "true"
```
3. Install Compass. ​There are three possible installation options:
### Kyma Compass
| Installation option | Value to use with the installation command | Example value |
|------------------------- |------------------- |------------------------- |
| From the `master` branch | `master` | `master` |
| From the specific commit on the `master` branch | `master-{COMMIT_HASH}` | `master-34edf09a` |
| From the specific PR | `PR-{PR_NUMBER}` | `PR-1420` |

This is a multi-tenant and multi-Runtime mode that provides a cluster with Compass and only the selected Kyma components that Compass uses. To enable this mode, create this ConfigMap and then perform the cluster Kyma installation using the
[`installer-cr-cluster-compass.yaml.tpl`](https://github.com/kyma-project/kyma/blob/master/installation/resources/installer-cr-cluster-compass.yaml.tpl) configuration file:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: compass-overrides
namespace: kyma-installer
labels:
installer: overrides
component: compass
kyma-project.io/installation: ""
data:
# The parameter that enables the Compass gateway, as the default Kyma gateway is disabled in this installation mode
gateway.gateway.enabled: "true"
# The name of the currently used gateway
global.istio.gateway.name: compass-istio-gateway
# The Namespace of the currently used gateway
global.istio.gateway.namespace: compass-system
# The parameter that disables preconfiguration for the Compass Runtime Agent
global.agentPreconfiguration: "false"
# The Namespace with a Secret that contains a certificate for the Connector Service
global.connector.secrets.ca.namespace: compass-system
Once you decide on the installation option, use this command:
```bash
kubectl apply -f https://storage.cloud.google.com/kyma-development-artifacts/compass/{INSTALLATION_OPTION}/compass-installer.yaml
```
​
4. Check the installation progress. To do so, download the script that checks the progress of the installation:
```bash
wget https://storage.cloud.google.com/kyma-development-artifacts/compass/{INSTALLATION_OPTION}/is-installed.sh && chmod +x ./is-installed.sh
```
​
Then, use the script to check the progress of the Compass installation:
```bash
./is-installed.sh
```

### Kyma Runtime
## Local installation

This is a single-tenant mode that provides complete cluster Kyma installation with the Runtime Agent. To enable this mode, follow the cluster Kyma installation using the [`installer-cr-cluster-runtime.yaml.tpl`](https://github.com/kyma-project/kyma/blob/master/installation/resources/installer-cr-cluster-runtime.yaml.tpl) configuration file. The default [legacy mode](#architecture-application-connector-components-application-operator) used in Kyma does not support integration with Compass. For that reason, before you start the installation, apply the following ConfigMap which disables components used in the legacy mode, such as the Application Registry and the Connector Service:
For local development, install Compass along with the minimal Kyma installation from the `master` branch. To do so, run this script:
```bash
./installation/cmd/run.sh
```

```yaml
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
name: disable-legacy-connectivity-override
namespace: kyma-installer
labels:
installer: overrides
kyma-project.io/installation: ""
data:
global.disableLegacyConnectivity: "true"
EOF
You can also specify Kyma version, such as 1.6 or newer:
```bash
./installation/cmd/run.sh {VERSION}
```

0 comments on commit f2eef91

Please sign in to comment.