Michman Initial Configuration¶

OpenStack configuration¶

Michman uses an service account from OpenStack cloud, all clusters are deployed in one project, specified by user.

For now we support following OpenStack versions:

• Stein
• Liberty
• Ussuri

Currently project supports deploying of services only on VMs with Ubuntu (16.04 or 18.04) or CentOS, so should be prepared suitable image.

It’s recomended to prepare floating ip pool and flavors for desired VMs.

Also you should prepare security key-pair and pem-key to provide access to created VMs from launcher service. Key should be pasted in $PROJECT_ROOT/launcher/ansible/files/ssh_key file or in Vault secrets storage.

You should download OpenStack RC File and write access information to the Vault secret storage. Specific fields for each version are listed below.

Set following parameters in config.yaml file:

• os_key_name: OS_KEY_NAME
• virtual_network: NETWORK
• floating_ip_pool: IP_POOL
• master_flavor: FLAVOR
• slaves_flavor: FLAVOR
• storage_flavor: FLAVOR
• os_version: VERSION #stein or liberty or ussuri

Secret storage configuration¶

We use Vault secret storage for securely accessing sensetive data like database credentials, cloud authentication data, etc.

Tested version: 1.2.3

You have to write to the Vault following secrets (Secret engine type - kv v1, path: kv/).

Openstack (os_key) secrets includes following keys for Liberty version:

• OS_AUTH_URL
• OS_PASSWORD
• OS_PROJECT_NAME
• OS_REGION_NAME
• OS_TENANT_ID
• OS_TENANT_NAME
• OS_USERNAME
• OS_SWIFT_USERNAME – optional
• OS_SWIFT_PASSWORD – optional

Openstack (os_key) secrets includes following keys for Stein version:

• OS_AUTH_URL
• OS_PASSWORD
• OS_PROJECT_NAME
• OS_REGION_NAME
• OS_USERNAME
• COMPUTE_API_VERSION
• NOVA_VERSION
• OS_AUTH_TYPE
• OS_CLOUDNAME
• OS_IDENTITY_API_VERSION
• OS_IMAGE_API_VERSION
• OS_NO_CACHE
• OS_PROJECT_DOMAIN_NAME
• OS_USER_DOMAIN_NAME
• OS_VOLUME_API_VERSION
• PYTHONWARNINGS
• no_proxy

Openstack (os_key) secrets includes following keys for Ussuri version:

• OS_AUTH_URL
• OS_PASSWORD
• OS_PROJECT_NAME
• OS_PROJECT_ID
• OS_REGION_NAME
• OS_USERNAME
• OS_IDENTITY_API_VERSION
• OS_PROJECT_DOMAIN_ID
• OS_USER_DOMAIN_NAME
• OS_INTERFACE

Ssh (ssh_key) secrets includes following keys:

• key_bgt – private ssh key for Ansible commands

Couchbase (cb_key) secretes includes following keys:

• clusterBucket – name of the bucket storing clusters
• password – password of couchbase
• path – address of couchbase
• username – user name of couchbase

Docker registry (registry_key) secret includes following key:

• url – Address of your selfsigned registry according to certificate or gitlab registry url
• user – Your selfsigned registry or gitlab username
• password – Your selfsigned registry or gitlab password

This secret is optional.

Hydra (hydra_key) secret includes following key:

• redirect_uri – OAuth 2.0 redirect URI
• client_id – OAuth 2.0 client ID
• client_secret – OAuth 2.0 client secret

This secret is optional, it is used only for oauth2 authorization model.

Also, you have to specify following fields in config.yaml:

• token: ROOT_TOKEN
• vault_addr: VAULT_ADDR
• os_key: BUCKET_PATH
• cb_key: BUCKET_PATH
• ssh_key: BUCKET_PATH
• hydra_key: BUCKET_PATH

Database configuration¶

We use Couchbase Server for storing orchestrator data about created clusters, projects, templates, supported services and images.

Tested version: 6.0.0 community edition.

Must contain prepared buckets with primary indexes: clusters, projects, templates, service_types, images. Templates bucket is optional and used only if you are going to create templates.

To work correctly with Michman you have to fill service_types and images buckets. You may use Michman REST API for this.

Register services you want to be supported in Michman. Json definitions of these services are listed in init directory. For example, register the spark service type:

curl -X POST -d "data=@michman/init/spark.json" http://michman_addr:michman_port/configs

Register cloud images you want to be supported in Michman. They must exist in your OpenStack cloud. For example, register the ubuntu image:

curl -X POST http://michman_addr:michman_port/configs -d
'{
        "Name": "ubuntu",
        "AnsibleUser": "ubuntu",
        "CloudImageID": "UUID"
}'

Also you may create user projects and general cluster templates via Michman REST API.

Logger configuration¶

Michman produces three types of logs: rest-service logs, launcher-service logs and cluster-logs.

Rest-service and launcher logs are stored in files in the $PROJECT_ROOT/logs directory and could be accessed via REST-api.

Cluster logs are the logs produced by Ansible on create, update and delete operations. Cluster logs could be stored in directory, specified by user, or in Logstash service.

If you want to store cluster logs in files, set following fields in config.yaml:

• logs_output: file
• log_file_path: PATH

If you want to store logs in Logstash storage, you have to deploy Logstash and Elasticsearch services, Kibana service is optional.

Modify Logstash config.conf file:

input{
        http {
                host => "0.0.0.0"
                port => 9000
        }
}
filter{
        mutate {
                add_field => { "[@metadata][target_index]" => "%{Cluster_name}" }
                remove_field => [ "Cluster_name" ]
        }
}
output {
        elasticsearch {
                        hosts => ["<ELASTICSEARCH_ADDR>:9200"]
                        index => "%{[@metadata][target_index]}"
        }
}

Then specify Logstash and Elasticsearch adresses in Michman config.yaml file:

• logs_output: logstash
• logstash_addr: xx.xx.xx.xx:xxxx
• elastic_addr: xx.xx.xx.xx:xxxx

Cluster logs could be accessed via REST API by the cluster ID.

Docker registry configurations¶

Currently Nextcloud service deployment is based on docker containers. It’s possible to use local registry:

1. Prepare your registry. It may be insecure registry (without any sertificates and user controls), selfsigned registry or gitlab registry.

2. Configure in config.yaml:

   1. If you use insecure registry, set:

      • docker_incecure_registry: true
      • insecure_registry_ip: xx.xx.xx.xx:xxxx

   2. If you use selfsigned registry, you need to set:

      • docker_selfsigned_registry: true
      • docker_selfsigned_registry_ip: xx.xx.xx.xx:xxxx
      • docker_selfsigned_registry_url: consides.to.cert.url
      • docker_cert_path: path_to_registry_cert.crt

   3. If you use gitlab registry you should set

      • docker_gitlab_registry: true

3. In case of using selfsigned or gitlab registry you should add secret with url, user and password to vault and set:

   • registry_key: key_of_docker_secret

Authentication and Authorization settings¶

Michman internal data model implies a logical division of cluster groups into projects. Users can view information about clusters only of the projects to which they belong. Based on this Michman supports three roles:

• admin - Michman administrator, can create new projects, add information about Michman supported services, add public cluster templates.
• user - has read access for paths not related to specific Michman projects.
• project_member - a member of the project, has access to paths within his project.

Michman doesn’t store information about users and their groups, so we provide user authentication via backend-services. For now are supported three models:

• OAUTH2.0
• OpenStack Keystone
• None-authentication mode

In the following sections, each model will be considered in detail.

OAUTH2.0 Authentication

OAuth2.0 authentication flow is implimented in Michman using two applications:

• ORY HYDRA – an implementation of the OAuth 2.0 Authorization Framework as well as the OpenID Connect Core 1.0 framework.
• Werther – an Identity Provider for ORY Hydra over LDAP. It implements Login And Consent Flow and provides basic UI.

This authentication type is used when you want to use Michman with your LDAP-server – users access Michman with their LDAP logins and information about users groups is retrieved from LDAP groups.

You have to deploy following services: Hydra Admin, Hydra Client and Werther, connected to your LDAP. The easiest way to do it is deploy these services using docker-compose from Wearthers README.

Be sure to specify the “groups” parameter, it will be used for user authorization in Michmans projects.

Be sure to specify the “groups” parameter in scopes and claims, it will be used for user authorization in Michmans projects.

You command should be like the following:

   hydra clients create     --skip-tls-verify --id test-client --secret test-secret --response-types code,id_token --grant-types authorization_code --token-endpoint-auth-method client_secret_post --scope openid,profile,email,groups --callbacks http://michman_addr:michman_port/auth --post-logout-callbacks http://michman_addr:michman_port/auth

Be sure to specify the “groups” parameter in scopes.

After services deploying you can pass authentication and authoriization in Michman following next steps.

1. Send authentication request to the Hydra Client service with grant_type code, groups must be specified in scope. Also in scopes must be specified openid parameter, other fields are optional (indicated here as an example):

http://hydra_client:4444/oauth2/auth?client_id=test-client&response_type=code&scope=openid%20profile%20email%20groups&state=12345678

1. Upon request, you will be redirected to the Werther login form in the browser. You must enter the login-password of the user defined in LDAP. If successful, it is redirected to the /auth path in michman. An authentication code will be added to the request parameters.

2. Continuation of authentication and authorization is handled in Michman:

   1. The “code” parameter is extracted from the request parameters

   2. A POST request is formed to obtain a token along the hydra-client:4444/auth2/token path, according to the specification.

   3. The processed response, if successful, contains the access token in the response body.

   4. Also GET request is formed along the hydra-client:4444/userinfo path. An authorization header is set in headers containing the previously obtained token. If successful:

      • information about the user’s groups is retrieved from the userinfo response;
      • a new session is established for the user;
      • user groups and access token are saved in the session parameters.

After this process you will be able to access projects, interconnected with your groups, and create new clusters in them. If “admin” group presents in groups list, you could access admin actions.

Without authentication you will obtain “user” role.

Also, you have to specify following fields in config.yaml:

• use_auth: true
• authorization_model: oauth2
• admin_group: admin
• session_idle_timeout: 480 #time in minutes, controls the maximum length of time a session can be inactive before it expires
• session_lifetime: 960 #time in minutes, controls the maximum length of time that a session is valid for before it expires
• hydra_admin: HYDRA_ADDR
• hydra_client: HYDRA_ADDR

Keystone Authentication

For this authentication type you should have an account in OpenStack Keystone. Pass the authentication in Keystone and obtain following tokens:

• X-Auth-Token
• X-Subject-Token

Then, start authentication and authorization process:

1. Go to the http://michman_addr:michman_port/auth, specifying X-Auth-Token and X-Subject-Token in headers.
2. The remaining process is handled in Michman. It sends the request to the Keystone on the token path: keystone_addr:keystone_port/v3/auth/tokens and retrieves information about user roles. User roles will be saved to the groups parameter in the user session.

After this process you will be able to access projects, interconnected with your groups, and create new clusters in them. If “admin” group presents in groups list, you could access admin actions.

Without authentication you will obtain “user” role.

Also, you have to specify following fields in config.yaml:

• use_auth: true
• authorization_model: keystone
• admin_group: admin
• session_idle_timeout: 480 #time in minutes, controls the maximum length of time a session can be inactive before it expires
• session_lifetime: 960 #time in minutes, controls the maximum length of time that a session is valid for before it expires
• keystone_addr: KEYSTONE_ADDR

None authentication mode

In addition, Michman supports none authentication mode, which could be used, for example, for development purposes. In this mode every user after authentication obtains “admin” role.

It includes the following steps:

1. Go to the http://michman_addr:michman_port/auth.
2. The remaining process is handled in Michman. It establishes the new user session and saves “admin” group to the groups parameter in this session.

Also, you have to specify following fields in config.yaml:

• use_auth: true
• authorization_model: none
• admin_group: admin
• session_idle_timeout: 480 #time in minutes, controls the maximum length of time a session can be inactive before it expires
• session_lifetime: 960 #time in minutes, controls the maximum length of time that a session is valid for before it expires

Off the authentication and authorization

You can completely disable authentication and authorization in the Michman system and work with Michman without session establishing.

If you want to do it, specify following field in config.yaml:

• use_auth: false