.. quickstart:

=================================
Kolla-Kubernetes Quickstart Guide
=================================

Install Kolla-Ansible
=====================

The kolla-ansible deliverable is a required dependency for generating the
default configuration consumed by kolla-kubernetes.  This is a short-term
development solution.  The medium term solution (Prior to May 2017) is to
entirely remove genconfig from the system and all reliance upon kolla-ansible
as a dependency such that kolla-kubernetes stands alone as a Kolla deliverable.

Install kolla-ansible:

::

    sudo pip install kolla-ansible

Configure Kolla-Kubernetes
==========================

Edit the file ``/etc/kolla/globals.yml`` to add these settings which
are specific to kolla-kubernetes:

::

    # Kolla-kubernetes custom configuration
    orchestration_engine: "KUBERNETES"
    api_interface_address: "0.0.0.0"
    memcached_servers: "memcached"
    keystone_database_address: "mariadb"
    keystone_admin_url: "http://keystone-admin:35357/v3"
    keystone_internal_url: "http://keystone-public:5000/v3"
    keystone_public_url: "http://keystone-public:5000/v3"
    glance_registry_host: "glance"

Then, generate the Kolla configuration files:

::

    # Generate Kolla Configuration Files
    sudo kolla-genpwd
    sudo kolla-ansible genconfig

If using a virt setup, set nova to use qemu unless your environment has
nested virt capabilities enabled::

    crudini --set /etc/kolla/nova-compute/nova.conf libvirt virt_type qemu

Labeling Nodes
==============

Your cluster needs to have at least one node labeled with each of the
following labels::

    kolla_compute=true
    kolla_controller=true

Label your current node::

    ALLINONENODE=$(hostname)
    kubectl label node $ALLINONENODE kolla_compute=true
    kubectl label node $ALLINONENODE kolla_controller=true

Alternately, you can override the default labeling used in the
``kolla-kubernetes.yml`` file. Similar mechanism (as of labeling individual
nodes) can be used to label a pool of nodes.

Setting Kubernetes Namespace
============================

Create the kubernetes namespace. By default it is ``kolla``.

::

    kubectl create namespace 'kolla'

When the namespace is created, each kubectl command executed against
the namespace requires adding ``--namespace=kolla`` keyword. The following
sequence of commands allow setting up the default kubectl context
with the right namespace and URL to kube-apiserver thus minimizing the amount
of typing one needs to do.

::

    kubectl config set-context kolla --namespace=kolla
    # X.X.X.X ip address of kubernetes api server
    kubectl config set-cluster kolla --server=http://X.X.X.X:8080
    kubectl config set-context kolla --cluster=kolla
    kubectl config use-context kolla

Generating Kubernetes Secrets
=============================

Before using this script, you MUST generate passwords by using
``generate_passwords.py`` (comes with kolla distribution), if there is no
``password.yml`` at ``/etc/kolla``, the script will generate an error.
Script accepts 1 parameter: ``create`` or ``delete``.

::

    # To create Secrets for all services in passwords.yml run:
    secret-generator.py create
    # To delete Secrets for all services in passwords.yml run:
    secret-generator.py delete

Resolv.conf Workaround
======================

Kubernetes uses service discovery for all pods including the ``net=host`` pods.
In the ``net=host`` pods, ``resolv.conf`` doesn't point at kube-dns. Kolla-kubernetes
provides a workaround by creating a configmap called resolv-conf with a
``resolv.conf`` from a non ``net=host`` pod so that dns properly resolves.

Create the resolv.conf configmap::

  ./tools/setup-resolv-conf.sh

Running Kolla-Kubernetes
========================

The following commands will walk through the deployment of the OpenStack
services. Before proceeding with the execution of each command below, ensure
that the previous command completes.

In the future, this will be handled as a workflow::

    for x in mariadb keystone horizon rabbitmq memcached nova-api \
             nova-conductor nova-scheduler glance-api-haproxy \
             glance-registry-haproxy glance-api glance-registry \
             neutron-server neutron-dhcp-agent neutron-l3-agent \
             neutron-metadata-agent neutron-openvswitch-agent \
             openvswitch-db-server openvswitch-vswitchd nova-libvirt \
             nova-compute nova-consoleauth nova-novncproxy \
             nova-novncproxy-haproxy neutron-server-haproxy \
             nova-api-haproxy cinder-api cinder-api-haproxy \
             cinder-backup cinder-scheduler cinder-volume \
             tgtd iscsid; \
    do
        kolla-kubernetes resource create configmap $x
    done
    for x in mariadb rabbitmq glance; do
        kolla-kubernetes resource create pv $x
        kolla-kubernetes resource create pvc $x
    done
    for x in mariadb memcached keystone-admin keystone-public rabbitmq \
             rabbitmq-management nova-api glance-api glance-registry \
             neutron-server nova-metadata nova-novncproxy horizon \
             cinder-api; \
    do
        kolla-kubernetes resource create svc $x
    done

    for x in mariadb-bootstrap rabbitmq-bootstrap; do
        kolla-kubernetes resource create bootstrap $x
    done
    watch kubectl get jobs --namespace kolla

wait for it....

::

    for x in mariadb-bootstrap rabbitmq-bootstrap; do
        kolla-kubernetes resource delete bootstrap $x
    done
    for x in mariadb memcached rabbitmq; do
        kolla-kubernetes resource create pod $x
    done
    watch kubectl get pods --namespace kolla

wait for it...

::

    for x in keystone-create-db keystone-endpoints keystone-manage-db; do
        kolla-kubernetes resource create bootstrap $x
    done
    watch kubectl get jobs --namespace kolla

wait for it...

::

    for x in keystone-create-db keystone-endpoints keystone-manage-db; do
        kolla-kubernetes resource delete bootstrap $x
    done
    kolla-kubernetes resource create pod keystone
    watch kolla-kubernetes resource status pod keystone

wait for it...

::

    for x in glance-create-db glance-endpoints glance-manage-db \
             nova-create-api-db nova-create-endpoints nova-create-db \
             neutron-create-db neutron-endpoints neutron-manage-db \
             cinder-create-db cinder-create-endpoints cinder-manage-db; \
    do
        kolla-kubernetes resource create bootstrap $x
    done
    watch kubectl get jobs --namespace=kolla

wait for it...

::

    for x in glance-create-db glance-endpoints glance-manage-db \
             nova-create-api-db nova-create-endpoints nova-create-db \
             neutron-create-db neutron-endpoints neutron-manage-db \
             cinder-create-db cinder-create-endpoints cinder-manage-db; \
    do
         kolla-kubernetes resource delete bootstrap $x
    done
    for x in nova-api nova-conductor nova-scheduler glance-api \
             glance-registry neutron-server horizon nova-consoleauth \
             nova-novncproxy cinder-api cinder-scheduler; \
    do
        kolla-kubernetes resource create pod $x
    done
    watch kubectl get pods --namespace=kolla

wait for it...

::

    for x in openvswitch-ovsdb-network openvswitch-vswitchd-network \
             neutron-openvswitch-agent-network neutron-dhcp-agent \
             neutron-metadata-agent-network neutron-l3-agent-network; \
    do
        kolla-kubernetes resource create pod $x
    done

    kolla-kubernetes resource create pod nova-libvirt
    kolla-kubernetes resource create pod nova-compute
    watch kubectl get pods --namespace=kolla

wait for it...

Services should be up now.

If you want to simply access the web gui, see section `Web Access`_ below.

Generate Credentials
====================

This will be automated by an "operator pod" in the future.
Credentials can be generated by hand by looking in ``/etc/kolla/globals.yml``
and filling in these variables::

  export OS_PROJECT_DOMAIN_ID=default
  export OS_USER_DOMAIN_ID=default
  export OS_PROJECT_NAME=admin
  export OS_USERNAME=admin
  export OS_PASSWORD=<keystone_admin_password>
  export OS_AUTH_URL=http://<kolla_internal_fqdn>:<keystone_admin_port>
  export OS_IDENTITY_API_VERSION=3

.. _`Web Access`:

Web Access
==========
If you want to access the horizon dashboard, fetch the admin password from
within the toolbox like:

::

    grep keystone_admin /etc/kolla/passwords.yml

.. NOTE:: statefulsets currently aren't deleted on delete. The resources for it will
          have to be cleaned up by hand.