Update 2017-01-10-Fedora25-Synapse-and-Your-Display-Server.adoc

= Fedora25: Synapse and Your Display Server
:hp-tags: fedora, linux, synapse, launcher, solution, terminal, display, wayland, Xorg

## The Problem

One of the tools I've constantly used when on a Linux distribution is https://launchpad.net/synapse-project[Synapse]. It's a really fast application launcher. I've tried https://github.com/ManuelSchneid3r/albert[albert] and others but none have pleased me as much. Since I switched to Fedora25 back in December 2016, I've been using GNOME's built in search which resides in the dashboard. It suffices but the rendering required can cause it to be a bit laggy when resources are being hogged (especially by Chome 😢). So I've decided to install Synapse. Unfortunately after installing, it wouldn't launch from the application menu. I opened Terminix and typed `synapse` only to see it crash from a segmentation fault 🤐. I decided to Google search the issue and came across these links:

- https://ask.fedoraproject.org/en/question/98598/i-get-a-segmentation-fault-when-starting-synapse-on-fedora-25-what-to-do/
- https://www.reddit.com/r/Fedora/comments/5j31sd/synapse_on_fedora_25_fails_with_segmentation/
- https://bugs.launchpad.net/synapse-project/+bug/1592008

Unfortunately everyone was complaining, but no solution.

## The Solution

I figured it was synapse trying to access memory or a stream that doesn't exist. So I checked `syanpse -h` to see what options are available. One of the options available to use `--display`. You can get synapse to successfully start by the following steps.

 1. check the location of the displays you have available: `cd /tmp/.X11-unix && for x in X*; do echo ":${x#X}"; done`
 2.  then, from the locations listed, try using any as arguments to the `--display` option.

For me, `synapse --display=:0` worked just fine.

**NB: This allows you to manually launch synapse. However, you MAY want to ensure that:**

 1. When you start synapse from the application menu it launches with the options you desire.

     * append ` --display=:0` to the end of `Exec=synapse` in the file `/usr/share/applications/synapse.desktop`.
     * You WILL need **sudo** access to do this. *Be mindful of the space in the string you will be appending.*

 2. If it's autostarted from your startup it is launched with the options you desire.
     * ensure you have **GNOME Tweak Tool** installed. *Install it using `sudo dnf install gnome-tweak-tool` or install it from the **Software** application*.
     * Then navigate: Tweak Tool>Startup Applications>➕. Search for Synapse then click "Add".

 3. Navigate Settings>Keyboard>➕. Enter Name: "Synapse", Command: "synapse --display=:0", Shortcut: [Whatever keyboard shortcut you desire].

This should suffice as a solution until a patch is made.

[footer]
This has been tested on fedora 25. Provide feedback as to whether it works on other distributions that are returning
```
[INFO 10:45:12.413170] [synapse-main:266] Starting up...
[INFO 10:45:12.625883] [synapse-main:208] Binding activation to <Control>space
[1]    27269 segmentation fault (core dumped)  synapse
```

= Fedora25: Synapse and Your Display Server
:hp-tags: fedora, linux, synapse, launcher, solution, terminal, display, wayland, Xorg

## The Problem

One of the tools I've constantly used when on a Linux distribution is https://launchpad.net/synapse-project[Synapse]. It's a really fast application launcher. I've tried https://github.com/ManuelSchneid3r/albert[albert] and others but none have pleased me as much. Since I switched to Fedora25 back in December 2016, I've been using GNOME's built in search which resides in the dashboard. It suffices but the rendering required can cause it to be a bit laggy when resources are being hogged (especially by Chome 😢). So I've decided to install Synapse. Unfortunately after installing, it wouldn't launch from the application menu. I opened Terminix and typed `synapse` only to see it crash from a segmentation fault 🤐. I decided to Google search the issue and came across these links:

- https://ask.fedoraproject.org/en/question/98598/i-get-a-segmentation-fault-when-starting-synapse-on-fedora-25-what-to-do/
- https://www.reddit.com/r/Fedora/comments/5j31sd/synapse_on_fedora_25_fails_with_segmentation/
- https://bugs.launchpad.net/synapse-project/+bug/1592008

Unfotunately everyone was complaining, but no solution.

## The Solution

I figured it was synapse trying to access memory or a stream that doesn't exist. So I checked `syanpse -h` to see what options are available. One of the options available to use `--display`. You can get synapse to successfully start by the following steps.

 1. check the location of the displays you have available: `cd /tmp/.X11-unix && for x in X*; do echo ":${x#X}"; done`
 2.  then, from the locations listed, try using any as arguments to the `--display` option.

For me, `synapse --display=:0` worked just fine.

**NB: This allows you to manually launch synapse. However, you MAY want to ensure that:**

 1. When you start synapse from the application menu it launches with the options you desire.

     * append ` --display=:0` to the end of `Exec=synapse` in the file `/usr/share/applications/synapse.desktop`.
     * You WILL need **sudo** access to do this. *Be mindful of the space in the string you will be appending.*

 2. If it's autostarted from your startup it is launched with the options you desire.
     * ensure you have **GNOME Tweak Tool** installed. *Install it using `sudo dnf install gnome-tweak-tool` or install it from the **Software** application*.
     * Then navigate: Tweak Tool>Startup Applications>➕. Search for Synapse then click "Add".

 3. Navigate Settings>Keyboard>➕. Enter Name: "Synapse", Command: "synapse --display=:0", Shortcut: [Whatever keyboard shortcut you desire].

This should suffice as a solution until a patch is made.

[footer]
This has been tested on fedora 25. Provide feedback as to whether it works on other distributions that are returning
```
[INFO 10:45:12.413170] [synapse-main:266] Starting up...
[INFO 10:45:12.625883] [synapse-main:208] Binding activation to <Control>space
[1]    27269 segmentation fault (core dumped)  synapse
```


Added Dynamic Provisioning for Ceph RBD

Added Dynamic Provisioning for Ceph RBD

Dynamic provisioning for Ceph RBD was implemented in Kubernetes in PR: https://github.com/kubernetes/kubernetes/pull/31251
So it is also a part of OpenShift.

That's why the Ceph RBD dynamic provisioner documentation is added.

[[install-config-persistent-storage-dynamically-provisioning-pvs]]
= Dynamic Provisioning and Creating Storage Classes
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
The *StorageClass* resource object is used to describe and classify storage that can be requested, as well as
provide a means for passing in parameters for *dynamically provisioned storage* on-demand.  StorageClasses can also serve
as a management mechanism for controlling different levels of storage and access to the storage.  Cluster Administrators (cluster-admin)
or Storage Administrators (storage-admin) need to define and create the StorageClasses that can then be requested by users without the users needing to have
any intimate knowledge about the underlying storage volume sources.

The Kubernetes
xref:../../architecture/additional_concepts/storage.adoc#architecture-additional-concepts-storage[persistent volume]
framework enables this functionality and allows administrators to provision a cluster with persistent storage
and gives users a way to request those resources without having any knowledge of
the underlying infrastructure.

Many storage types are available for use as persistent volumes in
{product-title}. While all of them can be statically provisioned by an
administrator, some types of storage can be created dynamically using the built in provider and plug-in APIs.

[[available-dynamically-provisioned-plug-ins]]
== Available Dynamically Provisioned Plug-ins

{product-title} provides the following _provisioner plug-ins_, which have
generic implementations for dynamic provisioning that use the cluster's
configured provider's API to create new storage resources:

[options="header"]
|===

|Storage Type |Provisioner Plug-in Name |Required Configuration| Notes

|OpenStack Cinder
|`kubernetes.io/cinder`
|xref:../../install_config/configuring_openstack.adoc#install-config-configuring-openstack[Configuring for OpenStack]
|

|AWS Elastic Block Store (EBS)
|`kubernetes.io/aws-ebs`
|xref:../../install_config/configuring_aws.adoc#install-config-configuring-aws[Configuring for AWS]
|For dynamic provisioning when using multiple clusters in different zones, each
node must be tagged with `*Key=KubernetesCluster,Value=clusterid*`.

|GCE Persistent Disk (gcePD)
|`kubernetes.io/gce-pd`
|xref:../../install_config/configuring_gce.adoc#install-config-configuring-gce[Configuring for GCE]
|In multi-zone configurations, PVs must be created in the same region/zone as
the master node. Do this by setting the
`*failure-domain.beta.kubernetes.io/region*` and
`*failure-domain.beta.kubernetes.io/zone*` PV labels to match the master node.

|GlusterFS
|`kubernetes.io/glusterfs`
|link:https://access.redhat.com/documentation/en/red-hat-gluster-storage/3.1/single/container-native-storage-for-openshift-container-platform/[Container Native Storage with GlusterFS]
|Container Native Storage (CNS) utilizes heketi to manage Gluster Storage

|Ceph RBD
|`kubernetes.io/rbd`
|xref:../../install_config/configuring_openstack.adoc#install-config-configuring-openstack[Configuring for OpenStack]
|

|===

[IMPORTANT]
====
For any chosen provisioner plug-ins, any relevant cloud, host or third-party configurations must also
be set up, per provider required documentation.
====

[[defining-storage-classes]]
== Defining a StorageClass

StorageClasses are currently a globally scoped object and need to be created by cluster-admins or
storage-admins.
There are currently five plug-ins that are supported. Below sections will
describe the basic Spec definition for a _StorageClass_ and specific examples for each of the supported plug-in types.

[[basic-spec-defintion]]
=== Basic StorageClass Spec Definition

.StorageClass Basic Spec Definition
====
[source,yaml]
----
kind: StorageClass <1>
apiVersion: storage.k8s.io/v1beta1 <2>
metadata:
  name: foo <3>
  annotations: <4>
     ...
provisioner: kubernetes.io/plug-in-type <5>
parameters: <6>
  param1: value
  ...
  paramN: value

----
<1> (required) The API object type.
<2> (required) The current apiVersion.
<3> (required) The name of the StorageClass.
<4> (optional) Annotations for the StorageClass
<5> (required) The type of provisioner associated with this storage class.
<6> (optional) The parameters required for the specific provisioner, this will change
from plug-in to plug-in.
====

[[storage-class-annotations]]
=== StorageClass Annotations

- Setting a _StorageClass_ as the cluster wide default _StorageClass_.  This will enable any Persistent Volume Claim (PVC)
that does not specify a specific volume to automatically be provisioned via the _default_ StorageClass
----
   storageclass.beta.kubernetes.io/is-default-class: "true"
----

- Setting a _StorageClass_ description
----
   kubernetes.io/description: My StorgeClass Description
----

[[openstack-cinder-spec]]
=== OpenStack Cinder Spec

.cinder-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: gold
provisioner: kubernetes.io/cinder
parameters:
  type: fast  <1>
  availability: nova <2>

----
<1> VolumeType created in Cinder. Default is empty.
<2> Availability Zone. Default is empty.
====

[[aws-elasticblockstore-ebs]]
=== AWS ElasticBlockStore (EBS)

.aws-ebs-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: slow
provisioner: kubernetes.io/aws-ebs
parameters:
  type: io1 <1>
  zone: us-east-1d <2>
  iopsPerGB: "10" <3>
  encrypted: true <4>
  kmsKeyId: keyvalue <5>

----

<1> io1, gp2, sc1, st1. See AWS docs for details. Default: gp2.
<2> AWS zone. If not specified, a random zone from those where Kubernetes cluster has a node is chosen.
<3> only for io1 volumes. I/O operations per second per GiB. AWS volume plug-in multiplies this with size of requested volume to compute IOPS of the volume and caps it at 20 000 IOPS (maximum supported by AWS, see AWS docs).
<4> denotes whether the EBS volume should be encrypted or not. Valid values are true or false.
<5> (optional) The full Amazon Resource Name (ARN) of the key to use when encrypting the volume. If none is supplied but encrypted is true, a key is generated by AWS. link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[See AWS docs for valid ARN value].
====

[[gce-persistentdisk-gcePd]]
=== GCE PersistentDisk (gcePD)

.gce-pd-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: slow
provisioner: kubernetes.io/gce-pd
parameters:
  type: pd-standard  <1>
  zone: us-central1-a  <2>

----

<1> pd-standard or pd-ssd. Default: pd-ssd
<2> GCE zone. If not specified, a random zone in the same region as controller-manager will be chosen.
====

[[glusterfs]]
=== GlusterFS

.glusterfs-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: slow
provisioner: kubernetes.io/glusterfs
parameters:
  endpoint: "glusterfs-cluster"  <1>
  resturl: "http://127.0.0.1:8081"  <2>
  restauthenabled: "true"  <3>
  restuser: "admin"  <4>
  restuserkey: "password"  <5>

----

<1> glusterfs-cluster is the endpoint name which includes GlusterFS trusted pool IP addresses. This parameter is mandatory. We need to also create a service for this endpoint, so that the endpoint will be persisted. This service can be without a selector to tell Kubernetes that the endpoints will be added manually. Please note that, glusterfs plug-in looks for the endpoint in the pod namespace, so it is mandatory that the endpoint and service have to be created in Pod's namespace for successful mount of gluster volumes in the pod.
<2> Gluster REST service/Heketi service url which provision gluster volumes on demand. The general format should be IPaddress:Port and this is a mandatory parameter for GlusterFS dynamic provisioner. If Heketi service is exposed as a routable service in openshift/kubernetes setup, it will have a resolvable fully qualified domain name and heketi service url. link:https://access.redhat.com/documentation/en/red-hat-gluster-storage/3.1/single/container-native-storage-for-openshift-container-platform/[For additional information and configuration]
<3> Gluster REST service/Heketi user who has access to create volumes in the Gluster Trusted Pool.
<4> Gluster REST service/Heketi user's password which will be used for authentication to the REST server. This parameter is deprecated in favor of secretNamespace + secretName.
<5> Identification of Secret instance that containes user password to use when talking to Gluster REST service. These parameters are optional, empty password will be used when both secretNamespace and secretName are omitted.
====

[[ceph-persistentdisk-cephRBD]]
=== Ceph RBD

.ceph-storageclass.yaml
====
[source,yaml]
----
apiVersion: storage.k8s.io/v1beta1
kind: StorageClass
metadata:
  name: fast
provisioner: kubernetes.io/rbd
parameters:
  monitors: 10.16.153.105:6789  <1>
  adminId: kube  <2>
  adminSecretName: ceph-secret  <3>
  adminSecretNamespace: kube-system  <4>
  pool: kube  <5>
  userId: kube  <6>
  userSecretName: ceph-secret-user  <7>

----

<1> Ceph monitors, comma delimited. It is required.
<2> Ceph client ID that is capable of creating images in the pool. Default is "admin".
<3> Secret Name for `adminId`. It is required. The provided secret must have type "kubernetes.io/rbd".
<4> The namespace for `adminSecret`. Default is "default".
<5> Ceph RBD pool. Default is "rbd".
<6> Ceph client ID that is used to map the RBD image. Default is the same as `adminId`.
<7> The name of Ceph Secret for `userId` to map RBD image. It must exist in the same namespace as PVCs. It is required.
====

[[moreinfo]]
== Additional Information and Examples

- xref:../../install_config/storage_examples/storage_classes_dynamic_provisioning.adoc#install-config-storage-examples-storage-classes-dynamic-provisioning[Examples and uses of StorageClasses for Dynamic Provisioning]

- xref:../../install_config/storage_examples/storage_classes_legacy.adoc#install-config-storage-examples-storage-classes-legacy[Examples and uses of StorageClasses without Dynamic Provisioning]

[[install-config-persistent-storage-dynamically-provisioning-pvs]]
= Dynamic Provisioning and Creating Storage Classes
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
The *StorageClass* resource object is used to describe and classify storage that can be requested, as well as
provide a means for passing in parameters for *dynamically provisioned storage* on-demand.  StorageClasses can also serve
as a management mechanism for controlling different levels of storage and access to the storage.  Cluster Administrators (cluster-admin)
or Storage Administrators (storage-admin) need to define and create the StorageClasses that can then be requested by users without the users needing to have
any intimate knowledge about the underlying storage volume sources.

The Kubernetes
xref:../../architecture/additional_concepts/storage.adoc#architecture-additional-concepts-storage[persistent volume]
framework enables this functionality and allows administrators to provision a cluster with persistent storage
and gives users a way to request those resources without having any knowledge of
the underlying infrastructure.

Many storage types are available for use as persistent volumes in
{product-title}. While all of them can be statically provisioned by an
administrator, some types of storage can be created dynamically using the built in provider and plug-in APIs.

[[available-dynamically-provisioned-plug-ins]]
== Available Dynamically Provisioned Plug-ins

{product-title} provides the following _provisioner plug-ins_, which have
generic implementations for dynamic provisioning that use the cluster's
configured provider's API to create new storage resources:

[options="header"]
|===

|Storage Type |Provisioner Plug-in Name |Required Configuration| Notes

|OpenStack Cinder
|`kubernetes.io/cinder`
|xref:../../install_config/configuring_openstack.adoc#install-config-configuring-openstack[Configuring for OpenStack]
|

|AWS Elastic Block Store (EBS)
|`kubernetes.io/aws-ebs`
|xref:../../install_config/configuring_aws.adoc#install-config-configuring-aws[Configuring for AWS]
|For dynamic provisioning when using multiple clusters in different zones, each
node must be tagged with `*Key=KubernetesCluster,Value=clusterid*`.

|GCE Persistent Disk (gcePD)
|`kubernetes.io/gce-pd`
|xref:../../install_config/configuring_gce.adoc#install-config-configuring-gce[Configuring for GCE]
|In multi-zone configurations, PVs must be created in the same region/zone as
the master node. Do this by setting the
`*failure-domain.beta.kubernetes.io/region*` and
`*failure-domain.beta.kubernetes.io/zone*` PV labels to match the master node.

|GlusterFS
|`kubernetes.io/glusterfs`
|link:https://access.redhat.com/documentation/en/red-hat-gluster-storage/3.1/single/container-native-storage-for-openshift-container-platform/[Container Native Storage with GlusterFS]
|Container Native Storage (CNS) utilizes heketi to manage Gluster Storage

|===

[IMPORTANT]
====
For any chosen provisioner plug-ins, any relevant cloud, host or third-party configurations must also
be set up, per provider required documentation.
====

[[defining-storage-classes]]
== Defining a StorageClass

StorageClasses are currently a globally scoped object and need to be created by cluster-admins or
storage-admins.
There are currently five plug-ins that are supported. Below sections will
describe the basic Spec definition for a _StorageClass_ and specific examples for each of the supported plug-in types.

[[basic-spec-defintion]]
=== Basic StorageClass Spec Definition

.StorageClass Basic Spec Definition
====
[source,yaml]
----
kind: StorageClass <1>
apiVersion: storage.k8s.io/v1beta1 <2>
metadata:
  name: foo <3>
  annotations: <4>
     ...
provisioner: kubernetes.io/plug-in-type <5>
parameters: <6>
  param1: value
  ...
  paramN: value

----
<1> (required) The API object type.
<2> (required) The current apiVersion.
<3> (required) The name of the StorageClass.
<4> (optional) Annotations for the StorageClass
<5> (required) The type of provisioner associated with this storage class.
<6> (optional) The parameters required for the specific provisioner, this will change
from plug-in to plug-in.
====

[[storage-class-annotations]]
=== StorageClass Annotations

- Setting a _StorageClass_ as the cluster wide default _StorageClass_.  This will enable any Persistent Volume Claim (PVC)
that does not specify a specific volume to automatically be provisioned via the _default_ StorageClass
----
   storageclass.beta.kubernetes.io/is-default-class: "true"
----

- Setting a _StorageClass_ description
----
   kubernetes.io/description: My StorgeClass Description
----

[[openstack-cinder-spec]]
=== OpenStack Cinder Spec

.cinder-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: gold
provisioner: kubernetes.io/cinder
parameters:
  type: fast  <1>
  availability: nova <2>

----
<1> VolumeType created in Cinder. Default is empty.
<2> Availability Zone. Default is empty.
====

[[aws-elasticblockstore-ebs]]
=== AWS ElasticBlockStore (EBS)

.aws-ebs-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: slow
provisioner: kubernetes.io/aws-ebs
parameters:
  type: io1 <1>
  zone: us-east-1d <2>
  iopsPerGB: "10" <3>
  encrypted: true <4>
  kmsKeyId: keyvalue <5>

----

<1> io1, gp2, sc1, st1. See AWS docs for details. Default: gp2.
<2> AWS zone. If not specified, a random zone from those where Kubernetes cluster has a node is chosen.
<3> only for io1 volumes. I/O operations per second per GiB. AWS volume plug-in multiplies this with size of requested volume to compute IOPS of the volume and caps it at 20 000 IOPS (maximum supported by AWS, see AWS docs).
<4> denotes whether the EBS volume should be encrypted or not. Valid values are true or false.
<5> (optional) The full Amazon Resource Name (ARN) of the key to use when encrypting the volume. If none is supplied but encrypted is true, a key is generated by AWS. link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[See AWS docs for valid ARN value].
====

[[gce-persistentdisk-gcePd]]
=== GCE PersistentDisk (gcePD)

.gce-pd-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: slow
provisioner: kubernetes.io/gce-pd
parameters:
  type: pd-standard  <1>
  zone: us-central1-a  <2>

----

<1> pd-standard or pd-ssd. Default: pd-ssd
<2> GCE zone. If not specified, a random zone in the same region as controller-manager will be chosen.
====

[[glusterfs]]
=== GlusterFS

.glusterfs-storageclass.yaml
====
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1beta1
metadata:
  name: slow
provisioner: kubernetes.io/glusterfs
parameters:
  endpoint: "glusterfs-cluster"  <1>
  resturl: "http://127.0.0.1:8081"  <2>
  restauthenabled: "true"  <3>
  restuser: "admin"  <4>
  restuserkey: "password"  <5>

----

<1> glusterfs-cluster is the endpoint name which includes GlusterFS trusted pool IP addresses. This parameter is mandatory. We need to also create a service for this endpoint, so that the endpoint will be persisted. This service can be without a selector to tell Kubernetes that the endpoints will be added manually. Please note that, glusterfs plug-in looks for the endpoint in the pod namespace, so it is mandatory that the endpoint and service have to be created in Pod's namespace for successful mount of gluster volumes in the pod.
<2> Gluster REST service/Heketi service url which provision gluster volumes on demand. The general format should be IPaddress:Port and this is a mandatory parameter for GlusterFS dynamic provisioner. If Heketi service is exposed as a routable service in openshift/kubernetes setup, it will have a resolvable fully qualified domain name and heketi service url. link:https://access.redhat.com/documentation/en/red-hat-gluster-storage/3.1/single/container-native-storage-for-openshift-container-platform/[For additional information and configuration]
<3> Gluster REST service/Heketi user who has access to create volumes in the Gluster Trusted Pool.
<4> Gluster REST service/Heketi user's password which will be used for authentication to the REST server. This parameter is deprecated in favor of secretNamespace + secretName.
<5> Identification of Secret instance that containes user password to use when talking to Gluster REST service. These parameters are optional, empty password will be used when both secretNamespace and secretName are omitted.
====

[[moreinfo]]
== Additional Information and Examples

- xref:../../install_config/storage_examples/storage_classes_dynamic_provisioning.adoc#install-config-storage-examples-storage-classes-dynamic-provisioning[Examples and uses of StorageClasses for Dynamic Provisioning]

- xref:../../install_config/storage_examples/storage_classes_legacy.adoc#install-config-storage-examples-storage-classes-legacy[Examples and uses of StorageClasses without Dynamic Provisioning]


RHDEVDOCS-3619: Update the creating applications flow as per the latest UI changes

// Module included in the following assemblies:
//
// * applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc

:_content-type: PROCEDURE
[id="odc-importing-codebase-from-git-to-create-application_{context}"]
= Importing a codebase from Git to create an application

You can use the *Developer* perspective to create, build, and deploy an application on {product-title} using an existing codebase in GitHub.

The following procedure walks you through the *From Git* option in the *Developer* perspective to create an application.

.Procedure

. In the *+Add* view, click *From Git* in the *Git Repository* tile to see the *Import from git* form.
. In the *Git* section, enter the Git repository URL for the codebase you want to use to create an application. For example, enter the URL of this sample Node.js application `\https://github.com/sclorg/nodejs-ex`. The URL is then validated.
. Optional: You can click *Show Advanced Git Options*  to add details such as:

* *Git Reference* to point to code in a specific branch, tag, or commit to be used to build the application.
* *Context Dir* to specify the subdirectory for the application source code you want to use to build the application.
* *Source Secret* to create a *Secret Name* with credentials for pulling your source code from a private repository.

. Optional: You can import a devfile, a Dockerfile, or a builder image through your Git repository to further customize your deployment.
* If your Git repository contains a devfile, a Dockerfile, or a builder image, it is automatically detected and populated on the respective path fields. If a devfile, a Dockerfile, and a builder image are detected in the same repository, the devfile is selected by default.
* To edit the file import type and select a different strategy, click *Edit import strategy* option.
* If multiple devfiles, Dockerfiles, or builder images are detected, to import a specific devfile, Dockerfile, or a builder image, specify the respective paths relative to the context directory.

. After the Git URL is validated, the recommended builder image is selected and marked with a star. If the builder image is not auto-detected, select a builder image. For the `https://github.com/sclorg/nodejs-ex` Git URL, by default the Node.js builder image is selected.
.. Optional: Use the *Builder Image Version* drop-down to specify a version.
.. Optional: Use the *Edit import strategy* to select a different strategy.
.. Optional: For the Node.js builder image, use the **Run command** field to override the command to run the application.

. In the *General* section:
.. In the *Application* field, enter a unique name for the application grouping, for example, `myapp`. Ensure that the application name is unique in a namespace.
.. The *Name* field to identify the resources created for this application is automatically populated based on the Git repository URL if there are no existing applications. If there are existing applications, you can choose to deploy the component within an existing application, create a new application, or keep the component unassigned.
+
[NOTE]
====
The resource name must be unique in a namespace. Modify the resource name if you get an error.
====

.  In the *Resources* section, select:

* *Deployment*, to create an application in plain Kubernetes style.
* *Deployment Config*, to create an {product-title} style application.
* *Serverless Deployment*, to create a Knative service.
+
[NOTE]
====
The *Serverless Deployment* option is displayed in the *Import from git* form only if the {ServerlessOperatorName} is installed in your cluster. For further details, refer to the {ServerlessProductName} documentation.
====

. In the *Pipelines* section, select *Add Pipeline*, and then click *Show Pipeline Visualization* to see the pipeline for the application.

. Optional: In the *Advanced Options* section, the *Target port* and the *Create a route to the application* is selected by default so that you can access your application using a publicly available URL.
+
If your application does not expose its data on the default public port, 80, clear the check box, and set the target port number you want to expose.

. Optional: You can use the following advanced options to further customize your application:

include::snippets/routing-odc.adoc[]
include::snippets/serverless-domain-mapping-odc.adoc[]

Health Checks::
Click the *Health Checks* link to add Readiness, Liveness, and Startup probes to your application. All the probes have prepopulated default data; you can add the probes with the default data or customize it as required.
+
To customize the health probes:
+
* Click *Add Readiness Probe*, if required, modify the parameters to check if the container is ready to handle requests, and select the check mark to add the probe.
* Click *Add Liveness Probe*, if required, modify the parameters to check if a container is still running, and select the check mark to add the probe.
* Click *Add Startup Probe*, if required, modify the parameters to check if the application within the container has started, and select the check mark to add the probe.
+
For each of the probes, you can specify the request type - *HTTP GET*, *Container Command*, or *TCP Socket*,  from the drop-down list. The form changes as per the selected request type. You can then modify the default values for the other parameters, such as the success and failure thresholds for the probe, number of seconds before performing the first probe after the container starts, frequency of the probe, and the timeout value.

Build Configuration and Deployment::
Click the *Build Configuration* and *Deployment* links to see the respective configuration options. Some options are selected by default; you can customize them further by adding the necessary triggers and environment variables.
+
For serverless applications, the *Deployment* option is not displayed as the Knative configuration resource maintains the desired state for your deployment instead of a `DeploymentConfig` resource.

include::snippets/scaling-odc.adoc[]

Resource Limit::
Click the *Resource Limit* link to set the amount of *CPU* and *Memory* resources a container is guaranteed or allowed to use when running.

Labels::
Click the *Labels* link to add custom labels to your application.

. Click *Create* to create the application and a success notification is displayed. You can see the build status of the application in the *Topology* view.

// Module included in the following assemblies:
//
// * applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc

:_content-type: PROCEDURE
[id="odc-importing-codebase-from-git-to-create-application_{context}"]
= Importing a codebase from Git to create an application

You can use the *Developer* perspective to create, build, and deploy an application on {product-title} using an existing codebase in GitHub.

The following procedure walks you through the *From Git* option in the *Developer* perspective to create an application.

.Procedure

. In the *+Add* view, click *From Git* in the *Git Repository* tile to see the *Import from git* form.
. In the *Git* section, enter the Git repository URL for the codebase you want to use to create an application. For example, enter the URL of this sample Node.js application `\https://github.com/sclorg/nodejs-ex`. The URL is then validated.
. Optional: You can click *Show Advanced Git Options*  to add details such as:

* *Git Reference* to point to code in a specific branch, tag, or commit to be used to build the application.
* *Context Dir* to specify the subdirectory for the application source code you want to use to build the application.
* *Source Secret* to create a *Secret Name* with credentials for pulling your source code from a private repository.

. Optional: You can import a devfile, a Dockerfile, or a builder image through your Git repository to further customize your deployment.
* If your Git repository contains a devfile, a Dockerfile, or a builder image, it is automatically detected and populated on the respective path fields. If a devfile, a Dockerfile, and a builder image are detected in the same repository, the devfile is selected by default.
* To edit the file import type and select a different strategy, click *Edit import strategy* option.
* If multiple devfiles, Dockerfiles, or builder images are detected, to import a specific devfile, Dockerfile, or a builder image, specify the respective paths relative to the context directory.

. After the Git URL is validated, the recommended builder image is selected and marked with a star. If the builder image is not auto-detected, select a builder image. For the `https://github.com/sclorg/nodejs-ex` Git URL, by default the Node.js builder image is selected.
.. Optional: Use the *Builder Image Version* drop-down to specify a version.
.. Optional: Use the *Edit import strategy* to select a different strategy.

. In the *General* section:
.. In the *Application* field, enter a unique name for the application grouping, for example, `myapp`. Ensure that the application name is unique in a namespace.
.. The *Name* field to identify the resources created for this application is automatically populated based on the Git repository URL if there are no existing applications. If there are existing applications, you can choose to deploy the component within an existing application, create a new application, or keep the component unassigned.
+
[NOTE]
====
The resource name must be unique in a namespace. Modify the resource name if you get an error.
====

.  In the *Resources* section, select:

* *Deployment*, to create an application in plain Kubernetes style.
* *Deployment Config*, to create an {product-title} style application.
* *Serverless Deployment*, to create a Knative service.
+
[NOTE]
====
The *Serverless Deployment* option is displayed in the *Import from git* form only if the {ServerlessOperatorName} is installed in your cluster. For further details, refer to the {ServerlessProductName} documentation.
====

. In the *Pipelines* section, select *Add Pipeline*, and then click *Show Pipeline Visualization* to see the pipeline for the application.

. In the *Advanced Options* section, the *Create a route to the application* is selected by default so that you can access your application using a publicly available URL. You can clear the check box if you do not want to expose your application on a public route.

. Optional: You can use the following advanced options to further customize your application:

include::snippets/routing-odc.adoc[]
include::snippets/serverless-domain-mapping-odc.adoc[]

Health Checks::
Click the *Health Checks* link to add Readiness, Liveness, and Startup probes to your application. All the probes have prepopulated default data; you can add the probes with the default data or customize it as required.
+
To customize the health probes:
+
* Click *Add Readiness Probe*, if required, modify the parameters to check if the container is ready to handle requests, and select the check mark to add the probe.
* Click *Add Liveness Probe*, if required, modify the parameters to check if a container is still running, and select the check mark to add the probe.
* Click *Add Startup Probe*, if required, modify the parameters to check if the application within the container has started, and select the check mark to add the probe.
+
For each of the probes, you can specify the request type - *HTTP GET*, *Container Command*, or *TCP Socket*,  from the drop-down list. The form changes as per the selected request type. You can then modify the default values for the other parameters, such as the success and failure thresholds for the probe, number of seconds before performing the first probe after the container starts, frequency of the probe, and the timeout value.

Build Configuration and Deployment::
Click the *Build Configuration* and *Deployment* links to see the respective configuration options. Some options are selected by default; you can customize them further by adding the necessary triggers and environment variables.
+
For serverless applications, the *Deployment* option is not displayed as the Knative configuration resource maintains the desired state for your deployment instead of a `DeploymentConfig` resource.

include::snippets/scaling-odc.adoc[]

Resource Limit::
Click the *Resource Limit* link to set the amount of *CPU* and *Memory* resources a container is guaranteed or allowed to use when running.

Labels::
Click the *Labels* link to add custom labels to your application.

. Click *Create* to create the application and see its build status in the *Topology* view.


Updated multi-cluster architecture scenario as per feedback

[[apim-kubernetes-operator-architecture]]
= GKO Architecture
:page-sidebar: apim_3_x_sidebar
:page-permalink: apim/3.x/apim_kubernetes_operator_architecture.html
:page-folder: apim/kubernetes
:page-layout: apim3x

== About Gravitee Kubernetes Operators

A link:https://kubernetes.io/docs/concepts/extend-kubernetes/operator/[Kubernetes operator^] is a method of packaging, deploying, and managing a Kubernetes application. A Kubernetes application is both deployed on Kubernetes and managed using the Kubernetes API and `kubectl` tooling.

In this context, a Kubernetes operator is an application-specific controller that extends the functionality of the Kubernetes API to create, configure, and manage application instances.

== Architecture overview

The current functionality of the Gravitee Kubernetes Operator (GKO) allows for three main deployment scenarios, as described below.

NOTE: To learn how to deploy GKO on a production cluster, see the link:{{ '/apim/3.x/apim_kubernetes_operator_installation_cluster.html' | relative_url }}[production deployment] section.

=== Standard deployment

In the standard deployment scenario, the Management API and the API Gateway are deployed in the same Kubernetes cluster.

With this workflow, the GKO listens for link:{{ '/apim/3.x/apim_kubernetes_operator_definitions.html' | relative_url }}[Custom Resource Definitions (CRDs] and for each custom resource, a link:https://kubernetes.io/docs/concepts/configuration/configmap/[ConfigMap^] is created and the API is pushed to the Management API using the import endpoint.

The API Gateway uses the link:https://github.com/gravitee-io/gravitee-kubernetes/tree/master/gravitee-kubernetes-client[Kubernetes Client^] to listen for `ConfigMap`s (with a custom label), and deploys the APIs accordingly.

The following diagram illustrates the standard deployment architectural approach:

image:{% link /images/apim/3.x/kubernetes/gko-architecture-1-standard.png %}[]

=== Deployment on multiple clusters

In this scenario, the assimption is that both of the following requirements should be met:

1. The user manages multiple Kubernetes clusters with a different set of APIs for each cluster.
2. All APIs are managed using a single API Console.

To make this work with GKO, it should be installed on all the required clusters.

The following diagram illustrates the multi-cluster deployment architectural approach:

image:{% link /images/apim/3.x/kubernetes/gko-architecture-2-multi-cluster.png %}[]

=== Deployment on multiple environments

In this scenario, a single GKO is deployed that can publish APIs to different environments (logical or physical). This is managed directly from the link:{{ '/apim/3.x/apim_kubernetes_operator_user_guide_api_definition.html' | relative_url }}[API Definition] custom resource, which refers a link:{{ '/apim/3.x/apim_kubernetes_operator_user_guide_management_context.html' | relative_url }}[Management Context] custom resource.

The following diagram illustrates the multi-environment deployment architectural approach:

image:{% link /images/apim/3.x/kubernetes/gko-architecture-3-multi-env.png %}[]

[[apim-kubernetes-operator-architecture]]
= GKO Architecture
:page-sidebar: apim_3_x_sidebar
:page-permalink: apim/3.x/apim_kubernetes_operator_architecture.html
:page-folder: apim/kubernetes
:page-layout: apim3x

== About Gravitee Kubernetes Operators

A link:https://kubernetes.io/docs/concepts/extend-kubernetes/operator/[Kubernetes operator^] is a method of packaging, deploying, and managing a Kubernetes application. A Kubernetes application is both deployed on Kubernetes and managed using the Kubernetes API and `kubectl` tooling.

In this context, a Kubernetes operator is an application-specific controller that extends the functionality of the Kubernetes API to create, configure, and manage application instances.

== Architecture overview

The current functionality of the Gravitee Kubernetes Operator (GKO) allows for three main deployment scenarios, as described below.

NOTE: To learn how to deploy GKO on a production cluster, see the link:{{ '/apim/3.x/apim_kubernetes_operator_installation_cluster.html' | relative_url }}[production deployment] section.

=== Standard deployment

In the standard deployment scenario, the Management API and the API Gateway are deployed in the same Kubernetes cluster.

With this workflow, the GKO listens for link:{{ '/apim/3.x/apim_kubernetes_operator_definitions.html' | relative_url }}[Custom Resource Definitions (CRDs] and for each custom resource, a link:https://kubernetes.io/docs/concepts/configuration/configmap/[ConfigMap^] is created and the API is pushed to the Management API using the import endpoint.

The API Gateway uses the link:https://github.com/gravitee-io/gravitee-kubernetes/tree/master/gravitee-kubernetes-client[Kubernetes Client^] to listen for `ConfigMap`s (with a custom label), and deploys the APIs accordingly.

The following diagram illustrates the standard deployment architectural approach:

image:{% link /images/apim/3.x/kubernetes/gko-architecture-1-standard.png %}[]

=== Deployment on multiple clusters

In this scenario, the assimption is that the user manages multiple Kubernetes clusters with a different set of APIs for each cluster. To make this work with GKO, it should be installed on all the required clusters.

The following diagram illustrates the multi-cluster deployment architectural approach:

image:{% link /images/apim/3.x/kubernetes/gko-architecture-2-multi-cluster.png %}[]

=== Deployment on multiple environments

In this scenario, a single GKO is deployed that can publish APIs to different environments (logical or physical). This is managed directly from the link:{{ '/apim/3.x/apim_kubernetes_operator_user_guide_api_definition.html' | relative_url }}[API Definition] custom resource, which refers a link:{{ '/apim/3.x/apim_kubernetes_operator_user_guide_management_context.html' | relative_url }}[Management Context] custom resource.

The following diagram illustrates the multi-environment deployment architectural approach:

image:{% link /images/apim/3.x/kubernetes/gko-architecture-3-multi-env.png %}[]


Wrong discovery.type for azure in breaking changes (#32432)

Should be `azure` instead of `aws`.

[[breaking_60_settings_changes]]
=== Settings changes

==== Remove support for elasticsearch.json and elasticsearch.yaml configuration file

The configuration file found in the Elasticsearch config directory could previously have
a `.yml`, `.yaml` or `.json` extension. Only `elasticsearch.yml` is now supported.

==== Duplicate keys in configuration file

In previous versions of Elasticsearch, the configuration file was allowed to
contain duplicate keys. For example:

[source,yaml]
--------------------------------------------------
node:
  name: my-node

node
  attr:
    rack: my-rack
--------------------------------------------------

In Elasticsearch 6.0.0, this is no longer permitted. Instead, this must be
specified in a single key as:

[source,yaml]
--------------------------------------------------
node:
  name: my-node
  attr:
    rack: my-rack
--------------------------------------------------

==== Coercion of boolean settings

Previously, Elasticsearch recognized the strings `true`, `false`, `on`, `off`, `yes`, `no`, `0`, `1` as booleans. Elasticsearch 6.0
recognizes only `true` and `false` as boolean and will throw an error otherwise. For backwards compatibility purposes, during the 6.x series
index settings on pre-6.0 indices will continue to work. Note that this does not apply to node-level settings that are stored
in `elasticsearch.yml`.

==== Snapshot settings

The internal setting `cluster.routing.allocation.snapshot.relocation_enabled` that allowed shards with running snapshots to be reallocated to
different nodes has been removed. Enabling this setting could cause allocation issues if a shard got allocated off a node and then
reallocated back to this node while a snapshot was running.

==== Store throttling settings

Store throttling has been removed. As a consequence, the
`indices.store.throttle.type` and `indices.store.throttle.max_bytes_per_sec`
cluster settings and the `index.store.throttle.type` and
`index.store.throttle.max_bytes_per_sec` index settings are not
recognized anymore.

==== Store settings

The `default` `index.store.type` has been removed. If you were using it, we
advise that you simply remove it from your index settings and Elasticsearch
will use the best `store` implementation for your operating system.

==== Network settings

The blocking TCP client, blocking TCP server, and blocking HTTP server have been removed.
As a consequence, the `network.tcp.blocking_server`, `network.tcp.blocking_client`,
`network.tcp.blocking`,`transport.tcp.blocking_client`, `transport.tcp.blocking_server`,
and `http.tcp.blocking_server` settings are not recognized anymore.

The previously unused settings `transport.netty.max_cumulation_buffer_capacity`,
`transport.netty.max_composite_buffer_components` and
`http.netty.max_cumulation_buffer_capacity` have been removed.

==== Similarity settings

The `base` similarity is now ignored as coords and query normalization have
been removed. If provided, this setting will be ignored and issue a
deprecation warning.

==== Script Settings

All of the existing scripting security settings have been removed.  Instead
they are replaced with `script.allowed_types` and `script.allowed_contexts`.

==== Discovery Settings

The `discovery.type` settings no longer supports the values `gce`, `azure` and `ec2`.
Integration with these platforms should be done by setting the `discovery.zen.hosts_provider` setting to
one of those values.

[[breaking_60_settings_changes]]
=== Settings changes

==== Remove support for elasticsearch.json and elasticsearch.yaml configuration file

The configuration file found in the Elasticsearch config directory could previously have
a `.yml`, `.yaml` or `.json` extension. Only `elasticsearch.yml` is now supported.

==== Duplicate keys in configuration file

In previous versions of Elasticsearch, the configuration file was allowed to
contain duplicate keys. For example:

[source,yaml]
--------------------------------------------------
node:
  name: my-node

node
  attr:
    rack: my-rack
--------------------------------------------------

In Elasticsearch 6.0.0, this is no longer permitted. Instead, this must be
specified in a single key as:

[source,yaml]
--------------------------------------------------
node:
  name: my-node
  attr:
    rack: my-rack
--------------------------------------------------

==== Coercion of boolean settings

Previously, Elasticsearch recognized the strings `true`, `false`, `on`, `off`, `yes`, `no`, `0`, `1` as booleans. Elasticsearch 6.0
recognizes only `true` and `false` as boolean and will throw an error otherwise. For backwards compatibility purposes, during the 6.x series
index settings on pre-6.0 indices will continue to work. Note that this does not apply to node-level settings that are stored
in `elasticsearch.yml`.

==== Snapshot settings

The internal setting `cluster.routing.allocation.snapshot.relocation_enabled` that allowed shards with running snapshots to be reallocated to
different nodes has been removed. Enabling this setting could cause allocation issues if a shard got allocated off a node and then
reallocated back to this node while a snapshot was running.

==== Store throttling settings

Store throttling has been removed. As a consequence, the
`indices.store.throttle.type` and `indices.store.throttle.max_bytes_per_sec`
cluster settings and the `index.store.throttle.type` and
`index.store.throttle.max_bytes_per_sec` index settings are not
recognized anymore.

==== Store settings

The `default` `index.store.type` has been removed. If you were using it, we
advise that you simply remove it from your index settings and Elasticsearch
will use the best `store` implementation for your operating system.

==== Network settings

The blocking TCP client, blocking TCP server, and blocking HTTP server have been removed.
As a consequence, the `network.tcp.blocking_server`, `network.tcp.blocking_client`,
`network.tcp.blocking`,`transport.tcp.blocking_client`, `transport.tcp.blocking_server`,
and `http.tcp.blocking_server` settings are not recognized anymore.

The previously unused settings `transport.netty.max_cumulation_buffer_capacity`,
`transport.netty.max_composite_buffer_components` and
`http.netty.max_cumulation_buffer_capacity` have been removed.

==== Similarity settings

The `base` similarity is now ignored as coords and query normalization have
been removed. If provided, this setting will be ignored and issue a
deprecation warning.

==== Script Settings

All of the existing scripting security settings have been removed.  Instead
they are replaced with `script.allowed_types` and `script.allowed_contexts`.

==== Discovery Settings

The `discovery.type` settings no longer supports the values `gce`, `aws` and `ec2`.
Integration with these platforms should be done by setting the `discovery.zen.hosts_provider` setting to
one of those values.