Browse Source

update of Installation Guide

added sections Manual Installation and Installation on DevStack

Change-Id: I206ae2e5fdd13a4cac700189d388578777b589c6
tags/6.0.0
tikitavi 1 year ago
parent
commit
41309f5922

+ 1
- 1
doc/source/conf.py View File

@@ -46,7 +46,7 @@ source_suffix = '.rst'
46 46
 master_doc = 'index'
47 47
 
48 48
 # General information about the project.
49
-project = 'ec2-api'
49
+project = 'EC2API Service'
50 50
 copyright = '2015, OpenStack Foundation'
51 51
 
52 52
 # If true, '()' will be appended to :func: etc. cross-reference text.

+ 3
- 1
doc/source/configuration/index.rst View File

@@ -1,3 +1,5 @@
1
+.. _configuring:
2
+
1 3
 ===================
2 4
 Configuring EC2-API
3 5
 ===================
@@ -11,7 +13,7 @@ To configure your EC2API installation, you must define configuration options in
11 13
 A list of config options based on different topics can be found below:
12 14
 
13 15
 .. toctree::
14
-   :maxdepth: 2
16
+   :maxdepth: 1
15 17
 
16 18
    api.rst
17 19
    metadata.rst

+ 14
- 2
doc/source/index.rst View File

@@ -3,14 +3,26 @@ OpenStack EC2 API
3 3
 
4 4
 Support of EC2 API for OpenStack.
5 5
 This project provides a standalone EC2 API service which pursues two goals:
6
+
6 7
 1. Implement VPC API which is now absent in nova's EC2 API
8
+
7 9
 2. Create a standalone service for EC2 API support which accommodates
8
-not only the VPC API but the rest of the EC2 API currently present in nova as
9
-well.
10
+   not only the VPC API but the rest of the EC2 API currently present in nova as
11
+   well.
10 12
 
11 13
 It doesn't replace existing nova EC2 API service in deployment, it gets
12 14
 installed to a different port (8788 by default).
13 15
 
16
+The ec2-api service consists of the following components:
17
+
18
+``ec2-api`` service
19
+  Accepts and responds to end user EC2 and VPC API calls.
20
+
21
+``ec2-api-metadata`` service
22
+  Provides the OpenStack Metadata API to servers. The metadata is used to
23
+  configure the running servers.
24
+
25
+
14 26
 Installing EC2API
15 27
 =================
16 28
 

+ 60
- 0
doc/source/install/configuration.rst View File

@@ -0,0 +1,60 @@
1
+.. _configuration:
2
+
3
+To configure OpenStack for EC2 API service add to ``/etc/ec2api/ec2api.conf``:
4
+
5
+.. code-block:: ini
6
+
7
+     [DEFAULT]
8
+     external_network = public
9
+     ec2_port = 8788
10
+     ec2api_listen_port = 8788
11
+     keystone_ec2_tokens_url = http://192.168.56.101/identity/v3/ec2tokens
12
+     api_paste_config = /etc/ec2api/api-paste.ini
13
+     disable_ec2_classic = True
14
+
15
+.. [*] - ``external_network`` option specifies the name of the external network,
16
+         which is used to Internet and to allocate Elastic IPs. It must be
17
+         specified to get access into VMs from outside of the cloud.
18
+
19
+       - ``disable_ec2_classic`` option is not mandatory, but we strongly
20
+         recommend it to be specified. It turns off EC2 Classic mode and forces
21
+         objects to be created inside VPCs.
22
+
23
+         With ``disable_ec2_classic`` = True, any user of the cloud must have
24
+         the only network (created with neutron directly and attached to a router
25
+         to provide outside access for that VMS), which is used for launch
26
+         ec2-classic instances.
27
+
28
+         Keep in mind that an operator is not able to change
29
+         ``disable_ec2_classic`` setting seamlessly.
30
+
31
+In the *[keystone_authtoken]* section, configure Identity service access.
32
+
33
+.. code-block:: ini
34
+
35
+     [keystone_authtoken]
36
+     project_domain_name = Default
37
+     project_name = service
38
+     user_domain_name = Default
39
+     password = password
40
+     username = ec2api
41
+     auth_type = password
42
+
43
+Also you need to configure database connection:
44
+
45
+.. code-block:: ini
46
+
47
+     [database]
48
+     connection = mysql+pymysql://root:password@127.0.0.1/ec2api?charset=utf8
49
+
50
+and cache if you want to use it.
51
+
52
+.. code-block:: ini
53
+
54
+     [cache]
55
+     backend = oslo_cache.dict
56
+     enabled = True
57
+
58
+You can look for other configuration options in the `Configuration Reference`_
59
+
60
+.. _`Configuration Reference`: ../configuration/api.html

+ 0
- 10
doc/source/install/credentials-creation.rst View File

@@ -1,18 +1,8 @@
1 1
 .. _credentials-creation:
2 2
 
3
-Creating the service credentials
4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5
-
6
-The service credentials are created automatically by the install.sh. To create
7
-them manually, complete these steps:
8
-
9 3
 #. Source the ``admin`` credentials to gain access to
10 4
    admin-only CLI commands:
11 5
 
12
-   .. code-block:: console
13
-
14
-      $ . admin-openrc
15
-
16 6
 #. To create the service credentials, complete these steps:
17 7
 
18 8
    * Create the ``ec2api`` user:

+ 1
- 8
doc/source/install/database-creation.rst View File

@@ -1,12 +1,5 @@
1 1
 .. _database-creation:
2 2
 
3
-Creating the database
4
-~~~~~~~~~~~~~~~~~~~~~
5
-
6
-The database is created automatically by the install.sh.
7
-
8
-To create the database manually, complete these steps:
9
-
10 3
 * Use the database access client to connect to the database
11 4
   server as the ``root`` user:
12 5
 
@@ -22,7 +15,7 @@ To create the database manually, complete these steps:
22 15
 
23 16
 * Grant proper access to the ``ec2api`` database:
24 17
 
25
-  .. code-block:: console
18
+  .. code-block:: ini
26 19
 
27 20
      GRANT ALL PRIVILEGES ON ec2api.* TO 'ec2api'@'localhost' \
28 21
       IDENTIFIED BY 'EC2-API_DBPASS';

+ 2
- 2
doc/source/install/endpoints-creation.rst View File

@@ -9,5 +9,5 @@ Create the ec2api service API endpoints:
9 9
    $ openstack endpoint create --region RegionOne ec2api \
10 10
      internal http://controller:XXXX/
11 11
 
12
-- where 'controller' is address of controller,
13
-- and 'XXXX' is port your ec2api is installed on (8788 by default)
12
+- where 'controller' is address your ec2api is installed on
13
+- and 'XXXX' is port (8788 by default)

+ 0
- 15
doc/source/install/get-started.rst View File

@@ -1,15 +0,0 @@
1
-=========================
2
-EC2-API service overview
3
-=========================
4
-
5
-The ec2-api service provides Amazon EC2 API support.
6
-
7
-The ec2-api service consists of the following components:
8
-
9
-``ec2-api`` service
10
-  Accepts and responds to end user EC2 and VPC API calls.
11
-
12
-``ec2-api-metadata`` service
13
-  Provides the OpenStack Metadata API to servers. The metadata is used to
14
-  configure the running servers.
15
-

+ 16
- 3
doc/source/install/index.rst View File

@@ -2,11 +2,24 @@
2 2
 Installing EC2-API
3 3
 =====================
4 4
 
5
+This section describes how to install and configure the ec2-api service on the
6
+controller node for Ubuntu (LTS).
7
+
8
+It assumes that you already have a working OpenStack environment with
9
+at least the following components installed: Compute, Networking, Block Storage,
10
+Identity, Image.
11
+
12
+.. toctree::
13
+   :maxdepth: 1
14
+
15
+   install-sh.rst
16
+   install-manual.rst
17
+   install-devstack.rst
18
+
19
+
5 20
 .. toctree::
6
-   :maxdepth: 2
21
+   :maxdepth: 1
7 22
 
8
-   get-started.rst
9
-   install.rst
10 23
    verify.rst
11 24
    next-steps.rst
12 25
 

+ 15
- 0
doc/source/install/install-devstack.rst View File

@@ -0,0 +1,15 @@
1
+.. _install-devstack:
2
+
3
+Installation on DevStack
4
+~~~~~~~~~~~~~~~~~~~~~~~~~
5
+
6
+In order to install ec2-api with devstack the following should be added to the local.conf or localrc the following line:
7
+
8
+.. code-block:: ini
9
+
10
+    enable_plugin ec2-api https://git.openstack.org/openstack/ec2-api
11
+
12
+Configuring OpenStack for EC2 API metadata service
13
+---------------------------------------------------
14
+
15
+.. include:: metadata-configuration.rst

+ 47
- 0
doc/source/install/install-manual.rst View File

@@ -0,0 +1,47 @@
1
+.. _install-manual:
2
+
3
+Manual Installation
4
+~~~~~~~~~~~~~~~~~~~
5
+
6
+Install and configure components
7
+--------------------------------
8
+
9
+1. Install the packages in any way you prefer
10
+   (**github+setup.py** / **pip** / **packages**)
11
+
12
+2. Create the service credentials
13
+
14
+   .. include:: credentials-creation.rst
15
+
16
+3. Create database
17
+
18
+   .. include:: database-creation.rst
19
+
20
+   There is a script creating 'ec2api' database that is accessible
21
+   only on localhost by user 'ec2api' with password 'ec2api'.
22
+   https://github.com/openstack/ec2-api/blob/master/tools/db/ec2api-db-setup
23
+
24
+4. Create endpoints:
25
+
26
+   .. include:: endpoints-creation.rst
27
+
28
+5. Create configuration files ``/etc/ec2api/api-paste.ini``
29
+   (can be copied from
30
+   https://github.com/openstack/ec2-api/blob/master/etc/ec2api/api-paste.ini)
31
+
32
+   and ``/etc/ec2api/ec2api.conf``
33
+
34
+   .. include:: configuration.rst
35
+
36
+6. Configure metadata:
37
+
38
+   .. include:: metadata-configuration.rst
39
+
40
+7. Start the services as binaries
41
+
42
+   .. code-block:: console
43
+
44
+       $ /usr/local/bin/ec2-api
45
+       $ /usr/local/bin/ec2-api-metadata
46
+
47
+   or set up as Linux services.

+ 38
- 0
doc/source/install/install-sh.rst View File

@@ -0,0 +1,38 @@
1
+.. _install-sh:
2
+
3
+Installation by install.sh
4
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
5
+
6
+Install and configure components
7
+--------------------------------
8
+
9
+Install the packages:
10
+
11
+.. code-block:: console
12
+
13
+   # apt-get update
14
+   # git clone https://github.com/openstack/ec2-api.git
15
+   # cd ec2-api
16
+
17
+Run install.sh
18
+
19
+The EC2 API service gets installed on port 8788 by default. It can be changed
20
+before the installation in ``/etc/ec2api/ec2api.conf`` configuration file.
21
+
22
+:ref:`configuring`.
23
+
24
+The services afterwards can be started as binaries:
25
+
26
+.. code-block:: console
27
+
28
+   $ /usr/local/bin/ec2-api
29
+   $ /usr/local/bin/ec2-api-metadata
30
+
31
+or set up as Linux services.
32
+
33
+.. include:: endpoints-creation.rst
34
+
35
+Configuring OpenStack for EC2 API metadata service
36
+---------------------------------------------------
37
+
38
+.. include:: metadata-configuration.rst

+ 12
- 57
doc/source/install/install-ubuntu.rst View File

@@ -1,64 +1,19 @@
1 1
 .. _install-ubuntu:
2 2
 
3
-Installation on existing OpenStack deployment
4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 3
 
6
-This section describes how to install and configure the ec2-api
7
-service for Ubuntu (LTS).
4
+Install and configure
5
+~~~~~~~~~~~~~~~~~~~~~
8 6
 
9
-Install and configure components
10
---------------------------------
7
+This section describes how to install and configure the ec2-api service on the
8
+controller node for Ubuntu (LTS).
11 9
 
12
-Install the packages:
10
+It assumes that you already have a working OpenStack environment with
11
+at least the following components installed: Compute, Networking, Block Storage,
12
+Identity, Image.
13 13
 
14
-.. code-block:: console
14
+.. toctree::
15
+   :maxdepth: 1
15 16
 
16
-   # apt-get update
17
-   # git clone https://github.com/openstack/ec2-api.git
18
-   # cd ec2-api
19
-
20
-Run install.sh
21
-
22
-The EC2 API service gets installed on port 8788 by default. It can be changed
23
-before the installation in install.sh script.
24
-
25
-The services afterwards can be started as binaries:
26
-
27
-::
28
-
29
-   /usr/local/bin/ec2-api
30
-   /usr/local/bin/ec2-api-metadata
31
-
32
-or set up as Linux services.
33
-
34
-.. include:: endpoints-creation.rst
35
-
36
-Configuring OpenStack for EC2 API metadata service
37
---------------------------------------------------
38
-
39
-To configure OpenStack for EC2 API metadata service:
40
-
41
-for Nova-network add:
42
-
43
-.. code-block:: console
44
-
45
-    # [DEFAULT]
46
-    # metadata_port = 8789
47
-    # [neutron]
48
-    # service_metadata_proxy = True
49
-
50
-to ``/etc/nova.conf``
51
-
52
-then restart nova-metadata (can be run as part of nova-api service) and
53
-nova-network services.
54
-
55
-for Neutron add:
56
-
57
-.. code-block:: console
58
-
59
-    # [DEFAULT]
60
-    # nova_metadata_port = 8789
61
-
62
-to ``/etc/neutron/metadata_agent.ini``
63
-
64
-then restart neutron-metadata service.
17
+   install-sh.rst
18
+   install-manual.rst
19
+   install-devstack.rst

+ 0
- 24
doc/source/install/install.rst View File

@@ -1,24 +0,0 @@
1
-.. _install:
2
-
3
-Install and configure
4
-~~~~~~~~~~~~~~~~~~~~~
5
-
6
-This section describes how to install and configure the ec2-api service on the
7
-controller node.
8
-
9
-This section assumes that you already have a working OpenStack environment with
10
-at least the following components installed: Compute, Networking, Block Storage,
11
-Identity, Image.
12
-
13
-.. toctree::
14
-   :maxdepth: 2
15
-
16
-   install-ubuntu.rst
17
-
18
-Additional steps:
19
-
20
-.. toctree::
21
-   :maxdepth: 2
22
-
23
-   database-creation.rst
24
-   credentials-creation.rst

+ 14
- 0
doc/source/install/metadata-configuration.rst View File

@@ -0,0 +1,14 @@
1
+EC2 metadata is built in between the nova-metadata and the neutron-metadata,
2
+so we need to configure Neutron so that it sends requests to ec2-api-metadata,
3
+not to the nova.
4
+
5
+To configure OpenStack for EC2 API metadata service for Neutron add:
6
+
7
+.. code-block:: ini
8
+
9
+    [DEFAULT]
10
+    nova_metadata_port = 8789
11
+
12
+to ``/etc/neutron/metadata_agent.ini``
13
+
14
+then restart neutron-metadata service.

+ 10
- 4
doc/source/install/verify.rst View File

@@ -14,7 +14,7 @@ Verify operation of the ec2-api service.
14 14
 
15 15
    .. code-block:: console
16 16
 
17
-      $ . admin-openrc
17
+      $ . openrc admin admin
18 18
 
19 19
 #. List service components to verify successful launch and registration
20 20
    of each process:
@@ -24,8 +24,14 @@ Verify operation of the ec2-api service.
24 24
       $ openstack service list
25 25
 
26 26
 
27
-#. Download aws cli from Amazon. Create configuration file for aws cli in your
28
-   home directory ``~/.aws/config``:
27
+#. Install aws cli.
28
+
29
+   .. code-block:: console
30
+
31
+      # pip install awscli --upgrade --user
32
+
33
+#. Create configuration file for aws cli in your home directory
34
+   ``~/.aws/config`` or by "**aws configure**" command:
29 35
 
30 36
    .. code-block:: console
31 37
 
@@ -36,7 +42,7 @@ Verify operation of the ec2-api service.
36 42
 
37 43
    Change the aws_access_key_id and aws_secret_acces_key above to the values
38 44
    appropriate for your cloud (can be obtained by
39
-   **"openstack ec2 credentials list"** command).
45
+   "**openstack ec2 credentials list**" command).
40 46
 
41 47
 #. Run aws cli commands using new EC2 API endpoint URL (can be obtained from
42 48
    keystone with the new port 8788) like this:

Loading…
Cancel
Save