Building Keystone - linux-on-ibm-z/docs GitHub Wiki

Building Keystone

Below versions of Keystone are available in respective distributions at the time of creation of these build instructions:

  • Ubuntu 20.04 has 17.0.1
  • Ubuntu 22.04 has 21.0.0

The instructions provided below specify the steps to build Keystone latest version on Linux on IBM Z for following distributions:

  • RHEL (8.6, 8.8, 8.9, 9.0, 9.2, 9.3)
  • SLES 15 SP4
  • Ubuntu (20.04, 22.04)

General notes:

  • When following the steps below please use a standard permission user unless otherwise specified
  • A directory /<source_root>/ will be referred to in these instructions, this is a temporary writable directory anywhere you'd like to place it

Note:

  • Keystone(v22.0.0) was verified at the time of creation of these instructions

Step 1: Build using script

If you want to build and install Keystone using manual steps, go to step 2.

Use the following commands to build Keystone using the build script. Please make sure you have wget installed.

wget https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/Keystone/22.0.0/build_keystone.sh

# Run bash build_keystone.sh -h to see all available options
bash build_keystone.sh

Step 2: Install the dependencies

 export SOURCE_ROOT=/<source_root>/

  • RHEL (8.6, 8.8, 8.9)

    sudo yum install -y python39-devel libffi-devel curl wget openssl-devel gcc make gcc-c++ python39-mod_wsgi httpd httpd-devel mariadb-server procps sqlite-devel python39-pip perl mariadb-devel mariadb-server

  • RHEL (9.0. 9.2, 9.3)

    sudo yum install -y python3-devel libffi-devel cargo curl wget openssl-devel gcc make gcc-c++ python3-mod_wsgi httpd httpd-devel procps sqlite-devel python3-pip perl
    • Add below content at end of /etc/yum.repos.d/MariaDB.repo file: 
      [mariadb]
name = MariaDB-10.11.7
baseurl=http://mirror.mariadb.org/mariadb-10.11.7/yum/rhel9-s390x
gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
gpgcheck=1
    • Install MariaDB: 
      sudo yum install -y MariaDB-devel mariadb-server

  • SLES 15 SP4

    sudo zypper install -y libopenssl-devel libffi-devel gcc make python310-devel python310-pip gawk apache2 apache2-devel mariadb libmariadb-devel gcc-c++ cargo curl wget

  • Ubuntu (20.04, 22.04)

    sudo apt-get update
sudo apt-get install -y python3-pip libffi-dev mysql-server libmysqlclient-dev libapache2-mod-wsgi-py3 apache2 apache2-dev wget curl uwsgi-plugin-python3

  • Install OpenSSL (For RHEL 9.x)

    cd $SOURCE_ROOT
wget https://www.openssl.org/source/old/1.1.1/openssl-1.1.1l.tar.gz
tar -xf openssl-1.1.1l.tar.gz
cd openssl-1.1.1l/
./config shared enable-ec_nistp_64_gcc_128 -Wl,-rpath=/usr/local/ssl/lib --prefix=/usr/local/ssl
make -j $(nproc)
sudo make install
hash -r
sudo ln -s /usr/local/ssl/bin/openssl /usr/local/bin/openssl
sudo mv /usr/bin/openssl /usr/bin/openssl_ORIG
sudo ln -s /usr/local/ssl/bin/openssl /usr/bin/openssl
openssl version

  • Install rustc (For RHEL 8.x, Ubuntu (20.04, 22.04))

    cd $SOURCE_ROOT
wget https://static.rust-lang.org/dist/rust-1.63.0-s390x-unknown-linux-gnu.tar.gz
tar -xzf rust-1.63.0-s390x-unknown-linux-gnu.tar.gz
cd rust-1.63.0-s390x-unknown-linux-gnu
sudo ./install.sh
export PATH=$HOME/.cargo/bin:$PATH
rustc -V
cargo  -V

Step 3: Set Environmental Variables

  • For RHEL (8.x, 9.x)
  export PATH=/usr/local/bin:$PATH

Step 4: Install additional python packages

  • RHEL (8.x, 9.x)

    sudo -H pip3 install --upgrade pip
sudo pip3 install alembic==1.8.1 amqp==5.1.1 aniso8601==9.0.1 appdirs==1.4.4 attrs==22.1.0 autopage==0.5.1 bcrypt==4.0.1 cachetools==5.2.0 certifi==2022.9.24 cffi==1.15.1 charset-normalizer==2.1.1 click==8.1.3 cliff==4.0.0 cmd2==2.4.2 cryptography debtcollector==2.5.0 decorator==5.1.1 defusedxml==0.7.1 dnspython==2.2.1 dogpile.cache==1.1.8 elementpath==3.0.2 eventlet==0.33.1 extras==1.0.0 fasteners==0.18 fixtures==4.0.1 Flask==2.1.0 Flask-RESTful==0.3.9 futurist==2.4.1 greenlet==2.0.1 idna==3.4 importlib-metadata==5.0.0 iso8601==1.1.0 itsdangerous==2.1.2 Jinja2==3.0.0 jmespath==1.0.1 jsonpatch==1.32 jsonpointer==2.3 jsonschema==4.17.0 keystone==22.0.0 keystoneauth1==5.0.0 keystonemiddleware==10.1.0 kombu==5.2.4 Mako==1.2.4 MarkupSafe==2.1.1 mod-wsgi==4.9.4 msgpack==1.0.4 munch==2.5.0 mysqlclient==2.1.1 netaddr==0.8.0 netifaces==0.11.0 oauthlib==3.2.2 openstacksdk==0.102.0 os-service-types==1.7.0 osc-lib==2.6.2 oslo.cache==3.3.0 oslo.concurrency==5.0.1 oslo.config==9.0.0 oslo.context==5.0.0 oslo.db==12.2.0 oslo.i18n==5.1.0 oslo.log==5.0.2 oslo.messaging==14.0.0 oslo.metrics==0.5.0 oslo.middleware==5.0.0 oslo.policy==4.0.0 oslo.serialization==5.0.0 oslo.service==3.0.0 oslo.upgradecheck==2.0.0 oslo.utils==6.0.1 osprofiler==3.4.3 packaging==21.3 passlib==1.7.4 Paste==3.5.2 PasteDeploy==3.0.1 pbr==5.11.0 prettytable==3.5.0 prometheus-client==0.15.0 pycadf==3.1.1 pycparser==2.21 pyinotify==0.9.6 PyJWT==2.6.0 pyOpenSSL==23.0.0 pyparsing==3.0.9 pyperclip==1.8.2 pyrsistent==0.19.2 pysaml2==7.2.1 python-cinderclient==9.1.0 python-dateutil==2.8.2 python-keystoneclient==5.0.1 python-novaclient==18.1.0 python-openstackclient==6.0.0 pytz==2022.6 PyYAML==6.0 repoze.lru==0.7 requests==2.28.1 requestsexceptions==1.4.0 rfc3986==2.0.0 Routes==2.5.1 scrypt==0.8.20 simplejson==3.18.0 six==1.16.0 SQLAlchemy==1.4.44 sqlalchemy-migrate==0.13.0 sqlparse==0.4.3 statsd==4.0.1 stevedore==4.1.1 Tempita==0.5.2 testresources==2.0.1 testscenarios==0.5.0 testtools==2.5.0 urllib3==1.26.12 vine==5.0.0 wcwidth==0.2.5 WebOb==1.8.7 Werkzeug==2.2.2 wrapt==1.14.1 xmlschema==2.1.1 yappi==1.4.0 zipp==3.10.0 uwsgi==2.0.24 --ignore-installed

  • SLES 15 SP4

    sudo -H pip3 install --upgrade pip
sudo pip3 install alembic==1.8.1 amqp==5.1.1 aniso8601==9.0.1 appdirs==1.4.4 attrs==22.1.0 autopage==0.5.1 bcrypt==4.0.1 cachetools==5.2.0 certifi==2022.9.24 cffi==1.15.1 charset-normalizer==2.1.1 click==8.1.3 cliff==4.0.0 cmd2==2.4.2 cryptography debtcollector==2.5.0 decorator==5.1.1 defusedxml==0.7.1 dnspython==2.2.1 dogpile.cache==1.1.8 elementpath==3.0.2 eventlet==0.33.1 extras==1.0.0 fasteners==0.18 fixtures==4.0.1 Flask==2.1.0 Flask-RESTful==0.3.9 futurist==2.4.1 greenlet==2.0.1 idna==3.4 importlib-metadata==5.0.0 iso8601==1.1.0 itsdangerous==2.1.2 Jinja2==3.0.0 jmespath==1.0.1 jsonpatch==1.32 jsonpointer==2.3 jsonschema==4.17.0 keystone==22.0.0 keystoneauth1==5.0.0 keystonemiddleware==10.1.0 kombu==5.2.4 Mako==1.2.4 MarkupSafe==2.1.1 mod-wsgi==4.9.4 msgpack==1.0.4 munch==2.5.0 mysqlclient==2.1.1 netaddr==0.8.0 netifaces==0.11.0 oauthlib==3.2.2 openstacksdk==0.102.0 os-service-types==1.7.0 osc-lib==2.6.2 oslo.cache==3.3.0 oslo.concurrency==5.0.1 oslo.config==9.0.0 oslo.context==5.0.0 oslo.db==12.2.0 oslo.i18n==5.1.0 oslo.log==5.0.2 oslo.messaging==14.0.0 oslo.metrics==0.5.0 oslo.middleware==5.0.0 oslo.policy==4.0.0 oslo.serialization==5.0.0 oslo.service==3.0.0 oslo.upgradecheck==2.0.0 oslo.utils==6.0.1 osprofiler==3.4.3 packaging==21.3 passlib==1.7.4 Paste==3.5.2 PasteDeploy==3.0.1 pbr==5.11.0 prettytable==3.5.0 prometheus-client==0.15.0 pycadf==3.1.1 pycparser==2.21 pyinotify==0.9.6 PyJWT==2.6.0 pyOpenSSL==23.0.0 pyparsing==3.0.9 pyperclip==1.8.2 pyrsistent==0.19.2 pysaml2==7.2.1 python-cinderclient==9.1.0 python-dateutil==2.8.2 python-keystoneclient==5.0.1 python-novaclient==18.1.0 python-openstackclient==6.0.0 pytz==2022.6 PyYAML==6.0 repoze.lru==0.7 requests==2.28.1 requestsexceptions==1.4.0 rfc3986==2.0.0 Routes==2.5.1 scrypt==0.8.20 simplejson==3.18.0 six==1.16.0 SQLAlchemy==1.4.44 sqlalchemy-migrate==0.13.0 sqlparse==0.4.3 statsd==4.0.1 stevedore==4.1.1 Tempita==0.5.2 testresources==2.0.1 testscenarios==0.5.0 testtools==2.5.0 urllib3==1.26.12 vine==5.0.0 wcwidth==0.2.5 WebOb==1.8.7 Werkzeug==2.2.2 wrapt==1.14.1 xmlschema==2.1.1 yappi==1.4.0 zipp==3.10.0 uwsgi==2.0.24 --ignore-installed

  • Ubuntu (20.04, 22.04)

    sudo -H pip3 install --upgrade pip
sudo pip3 install alembic==1.8.1 amqp==5.1.1 aniso8601==9.0.1 appdirs==1.4.4 attrs==22.1.0 autopage==0.5.1 bcrypt==4.0.1 cachetools==5.2.0 certifi==2022.9.24 cffi==1.15.1 charset-normalizer==2.1.1 click==8.1.3 cliff==4.0.0 cmd2==2.4.2 cryptography debtcollector==2.5.0 decorator==5.1.1 defusedxml==0.7.1 dnspython==2.2.1 dogpile.cache==1.1.8 elementpath==3.0.2 eventlet==0.33.1 extras==1.0.0 fasteners==0.18 fixtures==4.0.1 Flask==2.1.0 Flask-RESTful==0.3.9 futurist==2.4.1 greenlet==2.0.1 idna==3.4 importlib-metadata==5.0.0 iso8601==1.1.0 itsdangerous==2.1.2 Jinja2==3.0.0 jmespath==1.0.1 jsonpatch==1.32 jsonpointer==2.3 jsonschema==4.17.0 keystone==22.0.0 keystoneauth1==5.0.0 keystonemiddleware==10.1.0 kombu==5.2.4 Mako==1.2.4 MarkupSafe==2.1.1 mod-wsgi==4.9.4 msgpack==1.0.4 munch==2.5.0 mysqlclient==2.1.1 netaddr==0.8.0 netifaces==0.11.0 oauthlib==3.2.2 openstacksdk==0.102.0 os-service-types==1.7.0 osc-lib==2.6.2 oslo.cache==3.3.0 oslo.concurrency==5.0.1 oslo.config==9.0.0 oslo.context==5.0.0 oslo.db==12.2.0 oslo.i18n==5.1.0 oslo.log==5.0.2 oslo.messaging==14.0.0 oslo.metrics==0.5.0 oslo.middleware==5.0.0 oslo.policy==4.0.0 oslo.serialization==5.0.0 oslo.service==3.0.0 oslo.upgradecheck==2.0.0 oslo.utils==6.0.1 osprofiler==3.4.3 packaging==21.3 passlib==1.7.4 Paste==3.5.2 PasteDeploy==3.0.1 pbr==5.11.0 prettytable==3.5.0 prometheus-client==0.15.0 pycadf==3.1.1 pycparser==2.21 pyinotify==0.9.6 PyJWT==2.6.0 pyOpenSSL==23.0.0 pyparsing==3.0.9 pyperclip==1.8.2 pyrsistent==0.19.2 pysaml2==7.2.1 python-cinderclient==9.1.0 python-dateutil==2.8.2 python-keystoneclient==5.0.1 python-novaclient==18.1.0 python-openstackclient==6.0.0 pytz==2022.6 PyYAML==6.0 repoze.lru==0.7 requests==2.28.1 requestsexceptions==1.4.0 rfc3986==2.0.0 Routes==2.5.1 scrypt==0.8.20 simplejson==3.18.0 six==1.16.0 SQLAlchemy==1.4.44 sqlalchemy-migrate==0.13.0 sqlparse==0.4.3 statsd==4.0.1 stevedore==4.1.1 Tempita==0.5.2 testresources==2.0.1 testscenarios==0.5.0 testtools==2.5.0 urllib3==1.26.12 vine==5.0.0 wcwidth==0.2.5 WebOb==1.8.7 Werkzeug==2.2.2 wrapt==1.14.1 xmlschema==2.1.1 yappi==1.4.0 zipp==3.10.0 uwsgi==2.0.24 --ignore-installed

    Note: You may also use sudo env PATH=$PATH <command> if any command fails with command not found error.

Step 5: Configure and start MariaDB server

  • Initialize MariaDB server ( For RHEL 8.x and SLES)

    sudo /usr/bin/mysql_install_db --user=mysql

  • Start MariaDB service

    sudo /usr/bin/mysqld_safe --user=mysql &       # For RHEL 8.x, SLES 15 SP4
sudo mysqld_safe &                             # For RHEL 9.x, Ubuntu(20.04, 22.04)

Step 6: Create user and grant privileges on Keystone database

Note:

  • <KEYSTONE_HOST_IP>- IP of your machine where you are installing Keystone Service
  • <DB_HOST> - IP or HostName of machine,where the MariaDB service is running e.g. 127.0.0.1
  • <KEYSTONE_DBPASS> - database password for Keystone
  • <PASSWORD> - database password for root user

Follow below instruction to create Keystone database and grant required privileges:

  • Create database, grant privileges to "keystone" user

    sudo mysql -e "CREATE DATABASE keystone"
sudo mysql -e "CREATE USER 'keystone'@'localhost' IDENTIFIED BY '<KEYSTONE_DBPASS>'"
sudo mysql -e "CREATE USER 'keystone'@'%' IDENTIFIED BY '<KEYSTONE_DBPASS>'"
sudo mysql -e "GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%'"
sudo mysql -e "GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost'"

Step 7: Configure Keystone

sudo mkdir -p /etc/keystone/
cd /etc/keystone/
sudo wget -O keystone.conf https://docs.openstack.org/keystone/zed/_static/keystone.conf.sample
export OS_KEYSTONE_CONFIG_DIR=/etc/keystone

  • Edit keystone.conf file

    sudo sed -i "s|#connection = <None>|connection = mysql://keystone:<KEYSTONE_DBPASS>@localhost/keystone|g" /etc/keystone/keystone.conf
sudo sed -i "s|#provider = fernet|provider = fernet|g" /etc/keystone/keystone.conf

  • Populate Keystone database

    sudo keystone-manage db_sync

Step 8: Initialize fernet key repository

sudo groupadd keystone
sudo useradd -m -g keystone keystone
sudo mkdir -p /etc/keystone/fernet-keys
sudo chown -R keystone:keystone fernet-keys
sudo keystone-manage fernet_setup --keystone-user keystone --keystone-group keystone
sudo keystone-manage credential_setup --keystone-user keystone --keystone-group keystone

Step 9: Bootstrap the Identity service

sudo keystone-manage bootstrap \
--bootstrap-password ADMIN_PASS \
--bootstrap-admin-url http://<KEYSTONE_HOST_IP>:35357/v3/ \
--bootstrap-internal-url http://<KEYSTONE_HOST_IP>:5000/v3/ \
--bootstrap-public-url http://<KEYSTONE_HOST_IP>:5000/v3/ \
--bootstrap-region-id RegionOne

Note: You may also use sudo env PATH=$PATH <command> if any command fails with command not found or connection error for above steps.

Step 10: Start Keystone service

Follow below instructions to enable wsgi to serve Keystone requests

  • Edit httpd.conf

    • RHEL (8.x, 9.x)

      • Add below content at end of /etc/httpd/conf/httpd.conf file:

        ServerName <KEYSTONE_HOST_IP>
Include /etc/httpd/sites-enabled/
LoadModule wsgi_module /usr/local/lib64/python3.9/site-packages/mod_wsgi/server/mod_wsgi-py39.cpython-39-s390x-linux-gnu.so

    • SLES 15 SP4

      • Add below content at end of /etc/apache2/httpd.conf file:

        ServerName <KEYSTONE_HOST_IP>
Include /etc/apache2/sites-enabled/
LoadModule wsgi_module /usr/local/lib64/python3.10/site-packages/mod_wsgi/server/mod_wsgi-py310.cpython-310-s390x-linux-gnu.so

        Note: Comment out the below line in /etc/apache2/httpd.conf file if it exist:

        Include /etc/apache2/sysconfig.d/include.conf

  • Add wsgi-keystone.conf

    • RHEL (8.x, 9.x)

      sudo mkdir -p /etc/httpd/sites-available
sudo mkdir -p /etc/httpd/sites-enabled
sudo curl -SL -o wsgi-keystone.conf https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/Keystone/22.0.0/conf/rhel-wsgi-keystone.conf
sudo mv wsgi-keystone.conf /etc/httpd/sites-available/

    • SLES 15 SP4

      sudo mkdir -p /etc/apache2/sites-available
sudo mkdir -p /etc/apache2/sites-enabled
sudo curl -SL -o wsgi-keystone.conf https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/Keystone/22.0.0/conf/sles-wsgi-keystone.conf
sudo mv wsgi-keystone.conf /etc/apache2/sites-available/

  • Enable the Identity service virtual host

    • RHEL (8.x, 9.x)

      sudo ln -s /etc/httpd/sites-available/wsgi-keystone.conf /etc/httpd/sites-enabled

    • SLES 15 SP4

      sudo ln -s /etc/apache2/sites-available/wsgi-keystone.conf /etc/apache2/sites-enabled

    • Ubuntu (20.04, 22.04)

      sudo uwsgi --http-socket 127.0.0.1:5000 --plugin /usr/lib/uwsgi/plugins/python3_plugin.so --wsgi-file $(which keystone-wsgi-public) &

  • Start apache service

    • RHEL and SLES

      sudo /usr/sbin/httpd

Note:

  • This command internally starts Keystone service
  • Comment ulimit section if required, in file /usr/sbin/apache2ctl and restart apache

Step 11: Verify Keystone installation

  • Set variables

    export OS_USERNAME=admin
export OS_PASSWORD=ADMIN_PASS
export OS_PROJECT_NAME=admin
export OS_USER_DOMAIN_NAME=Default
export OS_PROJECT_DOMAIN_NAME=Default
export OS_AUTH_URL=http://<KEYSTONE_HOST_IP>:5000/v3
export OS_IDENTITY_API_VERSION=3

  • Create symlinks for RHEL (8.x, 9.x)

    sudo ln -s /usr/local/bin/keystone-wsgi-admin /bin/
sudo ln -s /usr/local/bin/keystone-wsgi-public /bin/

  • Run any Keystone command and check if it succeeds. For example

    openstack service list
openstack token issue

References:

The information provided in this article is accurate at the time of writing, but on-going development in the open-source projects involved may make the information incorrect or obsolete. Please open issue or contact us on IBM Z Community if you have any questions or feedback.

⚠️ **GitHub.com Fallback** ⚠️