<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter
[
  <!ENTITY % entities SYSTEM "entity-decl.ent">
    %entities;
]>
<chapter version="5.0" xml:id="cha-cap-install-stratos"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink">
 <info>
  <title>Installing the Stratos Web Console</title>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
   <dm:bugtracker></dm:bugtracker>
   <dm:translation>yes</dm:translation>
  </dm:docmanager>
 </info>

   <para>
   The Stratos user interface (UI) is a modern web-based management application
   for &cf;. It provides a graphical management console for both
   developers and system administrators.
  </para>

 <sect1 xml:id="sec-cap-stratos-prod">
  <title>Deploy Stratos on &susecaaspreg;</title>

   <para>
      The steps in this section describe how to install Stratos on &susecaaspreg;
      without an external load balancer, instead mapping a worker node to your
      &productname; domain as described in
      <xref linkend="sec-cap-caasp-config"/>. These instructions assume you
      have followed the procedure in <xref linkend="cha-cap-depl-caasp"/>,
      have deployed <literal>kubecf</literal> successfully, and have created a
      default storage class.
 </para>

  <para>
   If you are using &ses; as your storage back-end, copy the secret into the
   Stratos namespace:
  </para>

<screen>&prompt.user;kubectl get secret ceph-secret-admin --output json --namespace default | \
sed 's/"namespace": "default"/"namespace": "stratos"/' | kubectl create --filename -</screen>

  <para>
   You should already have the Stratos charts when you downloaded the &suse;
   charts repository (see <xref linkend="sec-cap-addrepo-caasp"/>). Search your
   &helm; repository to verify that you have the <literal>suse/console</literal>
   chart:
  </para>

&helm-search-suse;

  <para>
   Create a YAML file, called <filename>&stratos-values-file;</filename> in this
   example, and use it to make configurations to the Stratos &helm; chart.
  </para>

<screen>### example Stratos deployment configuration file
### &stratos-values-file;

console:
  # Use local admin user instead of UAA
  localAdminPassword: <replaceable>changeme</replaceable>
</screen>

  &stratos-tech-preview-note;

  <para>
   Create a namespace for your Stratos deployment.
  </para>

<screen>&prompt.user;kubectl create namespace <replaceable>stratos</replaceable></screen>

  <para>
   Deploy Stratos using &helm;.
  </para>

<screen>&prompt.user;helm install <replaceable>susecf-console</replaceable> suse/console \
--namespace <replaceable>stratos</replaceable> \
--values &stratos-values-file;
</screen>

  &stratos-deploy-complete;

  <para>
   When the <literal>stratos</literal> deployment completes, query with &helm;
   to view your release information:
  </para>

<screen>&prompt.user;helm status susecf-console
LAST DEPLOYED: Wed Mar 27 06:51:36 2019
NAMESPACE: stratos
STATUS: DEPLOYED

RESOURCES:
==> v1/Secret
NAME                           TYPE    DATA  AGE
susecf-console-secret          Opaque  2     3h
susecf-console-mariadb-secret  Opaque  2     3h

==> v1/PersistentVolumeClaim
NAME                                  STATUS  VOLUME                                    CAPACITY  ACCESSMODES  STORAGECLASS  AGE
susecf-console-upgrade-volume         Bound   pvc-711380d4-5097-11e9-89eb-fa163e15acf0  20Mi      RWO          persistent    3h
susecf-console-encryption-key-volume  Bound   pvc-711b5275-5097-11e9-89eb-fa163e15acf0  20Mi      RWO          persistent    3h
console-mariadb                       Bound   pvc-7122200c-5097-11e9-89eb-fa163e15acf0  1Gi       RWO          persistent    3h

==> v1/Service
NAME                    CLUSTER-IP      EXTERNAL-IP                                                PORT(S)   AGE
susecf-console-mariadb  172.24.137.195  &lt;none>                                                     3306/TCP  3h
susecf-console-ui-ext   172.24.80.22    10.86.101.115,172.28.0.31,172.28.0.36,172.28.0.7,172.28.0.22  8443/TCP  3h

==> v1beta1/Deployment
NAME        DESIRED  CURRENT  UP-TO-DATE  AVAILABLE  AGE
stratos-db  1        1        1           1          3h

==> v1beta1/StatefulSet
NAME     DESIRED  CURRENT  AGE
stratos  1        1        3h
</screen>

  <para>
  Find the external IP address with
  <command>kubectl get service susecf-console-ui-ext --namespace stratos</command> to access your new Stratos Web console, for example https://10.86.101.115:8443, or use the
          domain you created for it, and its port, for example
          https://example.com:8443. Proceed past the warnings about the self-signed
   certificates and log in as <literal>admin</literal> with the password you
   created in &stratos-values-file;
  </para>

  <!-- Image of Stratos UI console -->
  &stratos-figure;

  <sect2 xml:id="sec-cap-stratos-caasp-connect">
   <title>Connecting &susecaaspreg; to Stratos</title>

   <para>
    Stratos can show information from your &susecaaspreg; environment.
   </para>

   <para>
    To enable this, you must register and connect your &susecaaspreg; environment
    with Stratos.
   </para>

   <para>
    In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
    navigation and click on the <guimenu>+</guimenu> icon in the top-right of
    the view - you should be shown the "Register new Endpoint" view.
   </para>

   <procedure>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
      navigation and click on the <guimenu>+</guimenu> icon in the top-right of
      the view.
     </para>
    </step>
    <step>
     <para>
      On the <literal>Register a new Endpoint</literal> view, click the
      <literal>&caasp;</literal> button.
     </para>
    </step>
    <step>
     <para>
      Enter a memorable name for your &susecaaspreg; environment in the <guimenu>Name</guimenu>
      field. For example, <replaceable>my-endpoint</replaceable>.
     </para>
    </step>
    <step>
     <para>
      Enter the URL of the API server for your &kube; environment in the
      <guimenu>Endpoint Address</guimenu> field. Run <command>kubectl cluster-info</command>
      and use the value of <literal>&kube; master</literal> as the URL.
     </para>
<screen>&prompt.user;kubectl cluster-info</screen>
    </step>
    <step>
     <para>
      Activate the <guimenu>Skip SSL validation for the endpoint</guimenu> check box
      if using self-signed certificates.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Register</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Activate the <guimenu>Connect to my-endpoint now (optional).</guimenu> check box.
     </para>
    </step>
    <step>
     <para>
      Provide a valid <filename>kubeconfig</filename> file for your &susecaaspreg; environment.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Connect</guimenu>.
     </para>
    </step>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>&kube;</guimenu> in the left-hand side
      navigation. Information for your &susecaaspreg; environment should now be
      displayed as in the following figure.
     </para>
    </step>
   </procedure>

   <figure xml:id="stratos-kubernetes-view-caasp-png">
    <title>&kube; Environment Information on Stratos</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="stratos-kubernetes-view-caasp.png" format="PNG" width="75%"/>
     </imageobject>
    </mediaobject>
   </figure>
  </sect2>
 </sect1>

 <sect1 xml:id="sec-cap-stratos-eks">
  <title>Deploy Stratos on &eks;</title>

  <para>
   Before deploying Stratos, ensure <literal>kubecf</literal> has been successfully
   deployed on &eks; (see <xref linkend="cha-cap-depl-eks"/>).
  </para>
  <para>
   Configure a scoped storage class for your Stratos deployment. Create a configuration
   file, called <filename>scoped-storage-class.yaml</filename> in this example,
   using the following as a template. Specify the region you are using as the
   <literal>zone</literal> and be sure to include the letter (for example, the
   letter <literal>a</literal> in <literal>us-west-2a</literal>) identifier to indicate
   the Availability Zone used:
  </para>
<screen>kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: <replaceable>gp2scoped</replaceable>
provisioner: kubernetes.io/aws-ebs
parameters:
  type: gp2
  zone: <replaceable>"us-west-2a"</replaceable>
reclaimPolicy: Retain
mountOptions:
  - debug
</screen>
  <para>
   Create the storage class using the <filename>scoped-storage-class.yaml</filename>
   configuration file:
  </para>
<screen>&prompt.user;kubectl create --filename <replaceable>scoped-storage-class.yaml</replaceable></screen>
  <para>
   Verify the storage class has been created:
  </para>
<screen>&prompt.user;kubectl get storageclass
NAME            PROVISIONER             AGE
gp2 (default)   kubernetes.io/aws-ebs   1d
gp2scoped       kubernetes.io/aws-ebs   1d
</screen>

  <para>
   Create a YAML file, called <filename>&stratos-values-file;</filename> in this
   example, and use it to make configurations to the Stratos &helm; chart.
  </para>

<screen>### example Stratos deployment configuration file
### &stratos-values-file;

console:
  # Use local admin user instead of UAA
  localAdminPassword: <replaceable>changeme</replaceable>

services:
  loadbalanced: true

kube:
  storage_class:
    persistent: gp2scoped
</screen>

  &stratos-tech-preview-note;

  <para>
   Create a namespace for your Stratos deployment.
  </para>

<screen>&prompt.user;kubectl create namespace <replaceable>stratos</replaceable></screen>

  <para>
   Deploy Stratos using &helm;.
  </para>

<screen>&prompt.user;helm install <replaceable>susecf-console</replaceable> suse/console
\
--namespace <replaceable>stratos</replaceable> \
--values &stratos-values-file;
</screen>

  &stratos-deploy-complete;

  <para>
   Obtain the host name of the service exposed through the public load balancer:
  </para>
<screen>&prompt.user;kubectl get service susecf-console-ui-ext --namespace stratos</screen>
  <para>
   Use this host name to create a CNAME record. After the record is created,
   access the console in a web browser by navigating to the domain mapped to the
   host name of the service retrieved from the
   <command>kubectl get service</command> step. Upon successfully logging in,
   you should see something similar to the following figure.
  </para>

  <!-- Image of Stratos UI console -->
  &stratos-figure;

  <sect2 xml:id="sec-cap-stratos-eks-connect">
   <title>Connecting &eks; to Stratos</title>

   <para>
    Stratos can show information from your &eks; environment.
   </para>

   <para>
    To enable this, you must register and connect your &eks; environment
    with Stratos.
   </para>

   <para>
    In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
    navigation and click on the <guimenu>+</guimenu> icon in the top-right of
    the view - you should be shown the "Register new Endpoint" view.
   </para>

   <procedure>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
      navigation and click on the <guimenu>+</guimenu> icon in the top-right of
      the view.
     </para>
    </step>
    <step>
     <para>
      On the <literal>Register a new Endpoint</literal> view, click the
      <literal>&eks;</literal> button.
     </para>
    </step>
    <step>
     <para>
      Enter a memorable name for your &eks; environment in the <guimenu>Name</guimenu>
      field. For example, <replaceable>my-endpoint</replaceable>.
     </para>
    </step>
    <step>
     <para>
      Enter the URL of the API server for your &kube; environment in the
      <guimenu>Endpoint Address</guimenu> field. Run <command>kubectl cluster-info</command>
      and use the value of <literal>&kube; master</literal> as the URL.
     </para>
<screen>&prompt.user;kubectl cluster-info</screen>
    </step>
    <step>
     <para>
      Activate the <guimenu>Skip SSL validation for the endpoint</guimenu> check box
      if using self-signed certificates.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Register</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Activate the <guimenu>Connect to my-endpoint now (optional).</guimenu> check box.
     </para>
    </step>
    <step>
     <para>
      Enter the name of your &eks; cluster in the <guimenu>Cluster</guimenu>
      field.
     </para>
    </step>
    <step>
     <para>
      Enter your AWS Access Key ID in the <guimenu>Access Key ID</guimenu>
      field.
     </para>
    </step>
    <step>
     <para>
      Enter your AWS Secret Access Key in the <guimenu>Secret Access Key</guimenu>
      field.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Connect</guimenu>.
     </para>
    </step>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>&kube;</guimenu> in the left-hand side
      navigation. Information for your &eks; environment should now be displayed
      as in the following figure.
     </para>
    </step>
   </procedure>

   <!-- Image of Kubernetes information after connecting with Stratos -->
   &stratos-kubernetes-figure;

  </sect2>
 </sect1>
 <sect1 xml:id="sec-cap-stratos-aks">
  <title>Deploy Stratos on &aks;</title>

  <para>
   Before deploying Stratos, ensure <literal>kubecf</literal> has been successfully
   deployed on &aks; (see <xref linkend="cha-cap-depl-aks"/>).
  </para>

  <para>
   Create a YAML file, called <filename>&stratos-values-file;</filename> in this
   example, and use it to make configurations to the Stratos &helm; chart.
  </para>

<screen>### example Stratos deployment configuration file
### &stratos-values-file;

console:
  # Use local admin user instead of UAA
  localAdminPassword: <replaceable>changeme</replaceable>

services:
  loadbalanced: true
</screen>

  &stratos-tech-preview-note;

  <para>
   Create a namespace for your Stratos deployment.
  </para>

<screen>&prompt.user;kubectl create namespace <replaceable>stratos</replaceable></screen>

  <para>
   Deploy Stratos using &helm;.
  </para>

<screen>&prompt.user;helm install <replaceable>susecf-console</replaceable> suse/console
\
--namespace <replaceable>stratos</replaceable> \
--values &stratos-values-file;
</screen>

  &stratos-deploy-complete;

  <para>
   Obtain the IP address of the service exposed through the public load balancer:
  </para>
<screen>&prompt.user;kubectl get service susecf-console-ui-ext --namespace stratos</screen>
  <para>
   Use this IP address to create an A record. After the record is created,     
   access the console in a web browser by navigating to the domain mapped to the 
   IP address of the service retrieved from the                                   
   <command>kubectl get service</command> step. Upon successfully logging in,    
   you should see something similar to the following figure.
  </para>

  <!-- Image of Stratos UI console -->
  &stratos-figure;

  <sect2 xml:id="sec-cap-stratos-aks-connect">
   <title>Connecting &aks; to Stratos</title>

   <para>
    Stratos can show information from your &aks; environment.
   </para>

   <para>
    To enable this, you must register and connect your &aks; environment
    with Stratos.
   </para>

   <para>
    In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
    navigation and click on the <guimenu>+</guimenu> icon in the top-right of
    the view - you should be shown the "Register new Endpoint" view.
   </para>

   <procedure>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
      navigation and click on the <guimenu>+</guimenu> icon in the top-right of
      the view.
     </para>
    </step>
    <step>
     <para>
      On the <literal>Register a new Endpoint</literal> view, click the
      <literal>Azure AKS</literal> button.
     </para>
    </step>
    <step>
     <para>
      Enter a memorable name for your &aks; environment in the <guimenu>Name</guimenu>
      field. For example, <replaceable>my-endpoint</replaceable>.
     </para>
    </step>
    <step>
     <para>
      Enter the URL of the API server for your &kube; environment in the
      <guimenu>Endpoint Address</guimenu> field. Run <command>kubectl cluster-info</command>
      and use the value of <literal>&kube; master</literal> as the URL.
     </para>
<screen>&prompt.user;kubectl cluster-info</screen>
    </step>
    <step>
     <para>
      Activate the <guimenu>Skip SSL validation for the endpoint</guimenu> check box
      if using self-signed certificates.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Register</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Activate the <guimenu>Connect to my-endpoint now (optional).</guimenu> check box.
     </para>
    </step>
    <step>
     <para>
      Provide a valid <filename>kubeconfig</filename> file for your &aks; environment.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Connect</guimenu>.
     </para>
    </step>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>&kube;</guimenu> in the left-hand side
      navigation. Information for your &aks; environment should now be displayed
      as in the following figure.
     </para>
    </step>
   </procedure>

   <!-- Image of Kubernetes information after connecting with Stratos -->
   &stratos-kubernetes-figure;

  </sect2>
 </sect1>
 <sect1 xml:id="sec-cap-stratos-gke">
  <title>Deploy Stratos on &gke;</title>

  <para>
   Before deploying Stratos, ensure <literal>kubecf</literal> has been successfully
   deployed on &gke; (see <xref linkend="cha-cap-depl-gke"/>).
  </para>

<para>
   Create a YAML file, called <filename>&stratos-values-file;</filename> in this
   example, and use it to make configurations to the Stratos &helm; chart.
  </para>

<screen>### example Stratos deployment configuration file
### &stratos-values-file;

console:
  # Use local admin user instead of UAA
  localAdminPassword: <replaceable>changeme</replaceable>

services:
  loadbalanced: true
</screen>

  &stratos-tech-preview-note;

  <para>
   Create a namespace for your Stratos deployment.
  </para>

<screen>&prompt.user;kubectl create namespace <replaceable>stratos</replaceable></screen>

  <para>
   Deploy Stratos using &helm;.
  </para>

<screen>&prompt.user;helm install <replaceable>susecf-console</replaceable> suse/console
\
--namespace <replaceable>stratos</replaceable> \
--values &stratos-values-file;
</screen>

  &stratos-deploy-complete;

  <para>
   Obtain the IP address of the service exposed through the public load balancer:
  </para>
<screen>&prompt.user;kubectl get service susecf-console-ui-ext --namespace stratos</screen>
  <para>
   Use this IP address to create an A record. After the record is created,     
   access the console in a web browser by navigating to the domain mapped to the 
   IP address of the service retrieved from the                                   
   <command>kubectl get service</command> step. Upon successfully logging in,    
   you should see something similar to the following figure.
  </para>

  <!-- Image of Stratos UI console -->
  &stratos-figure;

  <sect2 xml:id="sec-cap-stratos-gke-connect">
   <title>Connecting &gke; to Stratos</title>

   <para>
    Stratos can show information from your &gke; environment.
   </para>

   <para>
    To enable this, you must register and connect your &gke; environment
    with Stratos.
   </para>

   <para>
    In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
    navigation and click on the <guimenu>+</guimenu> icon in the top-right of
    the view - you should be shown the "Register new Endpoint" view.
   </para>

   <procedure>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
      navigation and click on the <guimenu>+</guimenu> icon in the top-right of
      the view.
     </para>
    </step>
    <step>
     <para>
      On the <literal>Register a new Endpoint</literal> view, click the
      <literal>&gke-full;</literal> button.
     </para>
    </step>
    <step>
     <para>
      Enter a memorable name for your &aks; environment in the <guimenu>Name</guimenu>
      field. For example, <replaceable>my-endpoint</replaceable>.
     </para>
    </step>
    <step>
     <para>
      Enter the URL of the API server for your &kube; environment in the
      <guimenu>Endpoint Address</guimenu> field. Run <command>kubectl cluster-info</command>
      and use the value of <literal>&kube; master</literal> as the URL.
     </para>
<screen>&prompt.user;kubectl cluster-info</screen>
    </step>
    <step>
     <para>
      Activate the <guimenu>Skip SSL validation for the endpoint</guimenu> check box
      if using self-signed certificates.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Register</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Activate the <guimenu>Connect to my-endpoint now (optional).</guimenu> check box.
     </para>
    </step>
    <step>
     <para>
      Provide a valid <filename>Application Default Credentials</filename> file for your
      &gke; environment. Generate the file using the command below. The command saves the
      credentials to a file named <filename>application_default_credentials.json</filename>
      and outputs the path of the file.
     </para>
<screen>&prompt.user;gcloud auth application-default login</screen>
    </step>
    <step>
     <para>
      Click <guimenu>Connect</guimenu>.
     </para>
    </step>
    <step>
     <para>
      In the Stratos UI, go to <guimenu>&kube;</guimenu> in the left-hand side
      navigation. Information for your &gke; environment should now be displayed
      as in the following figure.
     </para>
    </step>
   </procedure>

   <!-- Image of Kubernetes information after connecting with Stratos -->
   &stratos-kubernetes-figure;
  </sect2>
 </sect1>
 <sect1 xml:id="sec-cap-stratos-upgrade">
  <title>Upgrading Stratos</title>

  <para>
   For instructions to upgrade Stratos, follow the process described in
   <xref linkend="cha-cap-upgrade"/>. Take note that <literal>kubecf</literal> is
   upgraded prior to upgrading Stratos.
  </para>
 </sect1>
 <sect1 xml:id="sec-cap-stratos-metrics">
  <title>Stratos Metrics</title>

  <para>
   Stratos Metrics provides a &helm; chart for deploying Prometheus (see
   <link xlink:href="https://prometheus.io/"/>) and the following metrics
   exporters to &kube;:
  </para>
  <itemizedlist>
   <listitem>
    <para>
     &cf; Firehose Exporter (enabled by default)
    </para>
   </listitem>
   <listitem>
    <para>
     &cf; Exporter (disabled by default)
    </para>
   </listitem>
   <listitem>
    <para>
     &kube; State Metrics Exporter (disabled by default)
    </para>
   </listitem>
  </itemizedlist>
  <para>
   The Stratos Metrics &helm; chart deploys a Prometheus server and the
   configured Exporters and fronts the Prometheus server with an nginx server
   to provide authenticated access to Prometheus (currently basic authentication
   over HTTPS).
  </para>
  <para>
   When required by configuration, it also contains an initialization script
   that will setup users in the UAA that have correct scopes/permissions to be
   able to read data from the &cf; Firehose and/or API.
  </para>
  <para>
   Lastly, the &helm; chart generates a small metadata file in the root of the
   nginx server that is used by Stratos to determine which &cf; and &kube;
   clusters the Prometheus server is providing Metrics for.
  </para>
  <para>
   To learn more about Stratos Metrics and its full list of configuration
   options, see <link xlink:href="https://github.com/SUSE/stratos-metrics"/>.
  </para>

  <sect2 xml:id="sec-cap-stratos-metrics-exporter-config">
   <title>Exporter Configuration</title>
   <sect3 xml:id="sec-cap-stratos-metrics-exporter-config-firehose">
    <title>Firehose Exporter</title>

    <para>
     This exporter can be enabled/disabled via the &helm; value
     <literal>firehoseExporter.enabled</literal>. By default this exporter is
     enabled.
    </para>
    <para>
You must provide the following Helm chart values for this Exporter to work correctly:
    </para>
    <itemizedlist>
     <listitem>
      <para>
       <literal>cloudFoundry.apiEndpoint</literal> - API Endpoint of the &cf;
       API Server
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>cloudFoundry.uaaAdminClient</literal> - Admin client of the UAA
       used by the &cf; server
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>cloudFoundry.uaaAdminClientSecret</literal> - Admin client
       secret of the UAA used by the &cf; server
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>cloudFoundry.skipSslVerification</literal> - Whether to skip SSL
       verification when communicating with &cf; and the UAA APIs
      </para>
     </listitem>
    </itemizedlist>
    <para>
     You can scale the firehose nozzle in Stratos Metrics by specifying the
     following override:
    </para>
<screen>
firehoseExporter:
  instances: 1
</screen>
    <para>
     Please note, the number of firehose nozzles should be proportional to the
     number of Traffic Controllers in your &cf; (see docs at
     <link xlink:href="https://docs.cloudfoundry.org/loggregator/log-ops-guide.html"/>).
     Otherwise, Loggregator will not split the firehose between the nozzles.
    </para>
   </sect3>
   <sect3 xml:id="sec-cap-stratos-metrics-exporter-config-cloud-foundry">
    <title>&cf; Exporter</title>

    <para>
     This exporter can be enabled/disabled via the &helm; value
     <literal>cfExporter.enabled</literal>. By default this exporter is
     disabled.
    </para>
    <para>
     You must provide the following &helm; chart values for this Exporter to
     work correctly:
    </para>
    <itemizedlist>
     <listitem>
      <para>
       <literal>cloudFoundry.apiEndpoint</literal> - API Endpoint of the &cf;
       API Server
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>cloudFoundry.uaaAdminClient</literal> - Admin client of the UAA
       used by the &cf; server
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>cloudFoundry.uaaAdminClientSecret</literal> - Admin client
       secret of the UAA used by the &cf; server
      </para>
     </listitem>
     <listitem>
      <para>
       <literal>cloudFoundry.skipSslVerification</literal> - Whether to skip SSL
       verification when communicating with &cf; and the UAA APIs
      </para>
     </listitem>
    </itemizedlist>
   </sect3>

   <sect3 xml:id="sec-cap-stratos-metrics-exporter-config-kubernetes">
    <title>&kube; Monitoring</title>

    <para>
     This exporter can be enabled/disabled via the &helm; value
     <literal>prometheus.kubeStateMetrics.enabled</literal>. By default this
     exporter is disabled.
    </para>
    <para>
     You must provide the following &helm; chart values for this Exporter to
     work correctly:
    </para>
    <itemizedlist>
     <listitem>
      <para>
       <literal>kubernetes.apiEndpoint</literal> - The API Endpoint of the
       &kube; API Server
      </para>
     </listitem>
    </itemizedlist>
   </sect3>
  </sect2>

  <sect2 xml:id="sec-cap-stratos-metrics-install">
   <title>Install Stratos Metrics with &helm;</title>
   <para>
    In order to display metrics data with Stratos, you need to deploy the
    <literal>stratos-metrics</literal> &helm; chart. As with othe examples in
    this guide, a YAML file is defined to change configurations of the &helm;
    chart.
   </para>
   <para>
    Create a new YAML file. In this example, it is named
    <filename>stratos-metrics-values.yaml</filename> and it contains
    configuration options specific to Stratos Metrics.
   </para>
   <para>
    The following is an example <filename>stratos-metrics-values.yaml</filename>
    file.
   </para>
<screen>cloudFoundry:
  apiEndpoint: <replaceable>https://api.example.com</replaceable>
  uaaAdminClient: admin
  uaaAdminClientSecret: <replaceable>password</replaceable>
  skipSslVerification: "true"
env:
  DOPPLER_PORT: 443
kubernetes:
  apiEndpoint: <replaceable>kube_server_address.example.com</replaceable>
metrics:
  username: <replaceable>username</replaceable>
  password: <replaceable>password</replaceable>
prometheus:
  kubeStateMetrics:
    enabled: true
  server:
    storageClass: <replaceable>"persistent"</replaceable>
services:
  loadbalanced: true</screen>
   <para>
    where:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      <literal>kubernetes.apiEndpoint</literal> is the same URL that you used
      when registering your &kube; environment with Stratos (the &kube; API
      Server URL).
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>prometheus.server.storageClass</literal> is the storage class to
      be used by Stratos Metrics. If a storage class is not assigned, the
      default storage class will be used. If a storage class is not specified
      and there is no default storage class, the <literal>prometheus</literal>
      pod will fail to start.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>metrics.username</literal> is the username used to authenticate
      with the nginx server that fronts Prometheus. This username is also used
      during the <xref linkend="sec-cap-stratos-metrics-connect"/>) process.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>metrics.password</literal> is the password used to authenticate
      with the nginx server that fronts Prometheus. This password is also used
      during the <xref linkend="sec-cap-stratos-metrics-connect"/>) process.
      Ensure a secure password is chosen.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>services.loadbalanced</literal> is set to <literal>true</literal>
      if your &kube; deployment supports automatic configuration of a load
      balancer (for example, AKS, EKS, and GKE).
     </para>
    </listitem>
   </itemizedlist>
   <para>
    If you are using &ses;, you must copy the Ceph admin secret to the
    <literal>metrics</literal> namespace:
   </para>
<screen>&prompt.user;kubectl get secret ceph-secret-admin --output json --namespace default | \
sed 's/"namespace": "default"/"namespace": "metrics"/' | kubectl create --filename -
</screen>
   <para>
    Install Metrics with:
   </para>
<screen>&prompt.user;kubectl create namespace <replaceable>metrics</replaceable>

&prompt.user;helm install <replaceable>susecf-metrics</replaceable> suse/metrics \
--namespace <replaceable>metrics</replaceable> \
--values &values-file; \
--values stratos-metrics-values.yaml</screen>
   <para>
    Monitor progress:
   </para>
<screen>$ watch --color 'kubectl get pods --namespace metrics'</screen>
   <para>
    When all statuses show <literal>Ready</literal>, press <keycombo>
    <keycap function="control"/> <keycap>C</keycap> </keycombo> to exit and to
    view your release information.
   </para>
  </sect2>

  <sect2 xml:id="sec-cap-stratos-metrics-connect">
   <title>Connecting Stratos Metrics</title>
   <para>
    When Stratos Metrics is connected to Stratos, additional views are enabled
    that show metrics metadata that has been ingested into the Stratos Metrics
    Prometheus server.
   </para>
   <para>
    To enable this, you must register and connect your Stratos Metrics instance
    with Stratos.
   </para>
   <para>
    In the Stratos UI, go to <guimenu>Endpoints</guimenu> in the left-hand side
    navigation and click on the <guimenu>+</guimenu> icon in the top-right of
    the view - you should be shown the "Register new Endpoint" view. Next:
   </para>
   <procedure>
    <step>
     <para>
      Select Metrics from the <guimenu>Endpoint Type</guimenu> dropdown.
     </para>
    </step>
    <step>
     <para>
      Enter a memorable name for your environment in the
      <guimenu>Name</guimenu> field.
     </para>
    </step>
    <step>
     <para>
      Enter the <guimenu>Endpoint Address</guimenu>. Use the following to find
      the endpoint value.
     </para>
<screen>&prompt.user;kubectl get service susecf-metrics-metrics-nginx --namespace metrics</screen>
     <itemizedlist>
      <listitem>
       <para>
	For &aks;, &eks;, and &gke; deployments which use a load balancer, the
	output will be similar to the following:
       </para>
<screen>
NAME                           TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)         AGE
susecf-metrics-metrics-nginx   LoadBalancer   10.0.202.180   52.170.253.229   443:30263/TCP   21h
</screen>
       <para>
        Preprend <literal>https://</literal> to the public IP of the load
        balancer, and enter it into the <guimenu>Endpoint Address</guimenu>
        field. Using the values from the example above,
        <literal>https://52.170.253.229</literal> is entered as the endpoint
        address.
       </para>
      </listitem>
      <listitem>
       <para>
        For &caasp; deployments which do not use a load balancer, the output
	will be similar to the following:
       </para>
<screen>
NAME                           TYPE       CLUSTER-IP       EXTERNAL-IP               PORT(S)         AGE
susecf-metrics-metrics-nginx   NodePort   172.28.107.209   10.86.101.115,172.28.0.31 443:30685/TCP   21h
</screen>
       <para>
        Prepend <literal>https://</literal> to the external IP of your node,
	followed by the <literal>nodePort</literal>, and enter it into the
        <guimenu>Endpoint Address</guimenu> field. Using the values from the
        example above, <literal>https://10.86.101.115:30685</literal> is entered
        as the endpoint address.
       </para>
      </listitem>
     </itemizedlist>
    </step>
    <step>
     <para>
      Check the <guimenu>Skip SSL validation for the endpoint</guimenu>
      checkbox if using self-signed certificates.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Finish</guimenu>.
     </para>
    </step>
   </procedure>
   <para>
    The view will refresh to show the new endpoint in the disconnected state.
    Next you will need to connect to this endpoint.
   </para>
   <para>
    In the table of endpoints, click the overflow menu icon alongside the
    endpoint that you added above, then:
   </para>
   <procedure>
    <step>
     <para>
      Click on <guimenu>Connect</guimenu> in the dropdown menu.
     </para>
    </step>
    <step>
     <para>
      Enter the username for your Stratos Metrics instance. This will be the
      <literal>metrics.username</literal> defined in your
      <filename>stratos-metrics-values.yaml</filename> file.
     </para>
    </step>
    <step>
     <para>
      Enter the password for your Stratos Metrics instance. This will be the
      <literal>metrics.password</literal> defined in your
      <filename>stratos-metrics-values.yaml</filename> file.
     </para>
    </step>
    <step>
     <para>
      Click <guimenu>Connect</guimenu>.
     </para>
    </step>
   </procedure>
   <para>
    Once connected, you should see that the name of your Metrics endpoint is a
    hyperlink and clicking on it should show basic metadata about the Stratos
    Metrics endpoint.
   </para>
   <para>
    Metrics data and views should now be available in the Stratos UI, for
    example:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      On the <guimenu>Instances</guimenu> tab for an Application, the table
      should show an additional Cell column to indicate which Diego Cell the
      instance is running on. This should be clickable to navigate to a Cell
      view showing Cell information and metrics.
     </para>
     <figure xml:id="stratos-app-instances-metrics-png">
      <title>Cell Column on Application Instance Tab after Connecting Stratos Metrics</title>
      <mediaobject>
       <imageobject>
        <imagedata fileref="stratos-app-instances-metrics.png" format="PNG" width="75%"/>
       </imageobject>
      </mediaobject>
     </figure>
    </listitem>
    <listitem>
     <para>
      On the view for an Application there should be a new Metrics tab that
      shows Application metrics.
     </para>
     <figure xml:id="stratos-app-metrics-tab-png">
      <title>Application Metrics Tab after Connecting Stratos Metrics</title>
      <mediaobject>
       <imageobject>
        <imagedata fileref="stratos-app-metrics-tab.png" format="PNG" width="75%"/>
       </imageobject>
      </mediaobject>
     </figure>
    </listitem>
    <listitem>
     <para>
      On the &kube; views, views such as the Node view should show an
      additional <guimenu>Metrics</guimenu> tab with metric information.
     </para>
     <figure xml:id="stratos-kubernetes-node-metrics-png">
      <title>Node Metrics on the Stratos &kube; View</title>
      <mediaobject>
       <imageobject>
        <imagedata fileref="stratos-kubernetes-node-metrics.png" format="PNG" width="75%"/>
       </imageobject>
      </mediaobject>
     </figure>
    </listitem>
   </itemizedlist>
  </sect2>
 </sect1>
</chapter>
