You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/connection-setup.rst
+89-75Lines changed: 89 additions & 75 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,139 +5,153 @@ Connection Setup
5
5
Overview
6
6
********
7
7
8
-
This page provides the steps necessary to get going with data ingestion and
9
-
querying of the PDS Registry Service on the cloud from the perspective of a Discipline
10
-
Node (DN).
8
+
Steps to connect a Discipline Node (DN) to the PDS Registry Service for data ingestion and querying.
11
9
12
-
Initial Set-up
13
-
**************
14
10
15
-
To get things going, you should have provided the Engineering Node contact with the following:
11
+
Prerequisites
12
+
*************
16
13
17
-
* A list of user email addresses which will be authorized to perform data ingestion.
18
-
* A list of IP addresses or blocks of addresses from which data ingestion will occur.
14
+
Before starting, contact the Engineering Node (pds-operator@jpl.nasa.gov) and provide:
19
15
20
-
The IP addresses are added to an access whitelist.
16
+
1. A list of user email addresses that need data ingestion access.
17
+
2. A list of IP addresses or CIDR blocks from which ingestion will occur.
21
18
22
-
Opensearch accounts will be set up for each user and their username and (temporary)
23
-
password will be sent to them.
19
+
The Engineering Node will:
24
20
25
-
Along with your Opensearch user credentials you will receive configuration inputs for your tools to connect to the registry services.
21
+
- Add your IPs to the access whitelist.
22
+
- Create OpenSearch accounts and send each user their username and temporary password.
23
+
- Send configuration inputs for connecting your tools to the registry.
26
24
27
-
The following sections provide the steps to follow to have your connection set up.
28
25
29
-
Changing Your Opensearch Password
30
-
*********************************
26
+
Change Your OpenSearch Password
27
+
********************************
31
28
32
-
To update your user password click `here <https://pds-prod-nucleus-dum.auth.us-west-2.amazoncognito.com/login?client_id=3rgdgts818hdrkas4q66lebum0&response_type=code&scope=email+openid&redirect_uri=https%3A%2F%2Fnasa-pds.github.io%2Fnucleus%2F>`_ and select "Forgot your password".
29
+
1. Go to the `OpenSearch password reset page <https://pds-prod-nucleus-dum.auth.us-west-2.amazoncognito.com/login?client_id=3rgdgts818hdrkas4q66lebum0&response_type=code&scope=email+openid&redirect_uri=https%3A%2F%2Fnasa-pds.github.io%2Fnucleus%2F>`_.
30
+
2. Select **Forgot your password** and follow the prompts.
33
31
34
32
35
-
Registry Tools Configurations
36
-
******************************
33
+
Registry Tools Configuration
34
+
*****************************
37
35
38
-
Have a Secure Directory For Your Configurations
39
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36
+
Create a Secure Configuration Directory
37
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40
38
41
-
Create a secure directory to place config files: Two of the config files you will be creating should be placed in a secure location accessible only by the current user.
39
+
Config files containing credentials must be stored in a directory accessible only by the current user.
42
40
43
-
On **Linux** and Linux-like Operating Systems:
41
+
**Linux / macOS:**
44
42
45
-
Create new ``$HOME/.auth directory``
43
+
1. Create the directory:
46
44
47
-
Change access to this directory to be only current user accessible only:
45
+
.. code:: bash
48
46
49
-
.. code:: bash
47
+
mkdir -p $HOME/.pds
50
48
51
-
chmod 700 $HOME/.auth
49
+
2. Restrict access to the current user only:
52
50
51
+
.. code:: bash
53
52
54
-
On **Windows**:
53
+
chmod 700 $HOME/.pds
55
54
56
-
Take the necessary precautions so that the directory is not readable by anyone but its owner.
55
+
**Windows:**
57
56
57
+
1. Create the ``%USERPROFILE%\.pds`` directory.
58
+
2. Set folder permissions so only your user account has read/write access.
58
59
59
-
Authentication file
60
-
~~~~~~~~~~~~~~~~~~~~
61
60
62
-
Create Harvest authentication file
63
-
Create a ``registry-auth.txt`` file with your username and password, and place it in the secure location created above.
61
+
Create the Authentication File
62
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64
63
65
-
.. code:: javascript
64
+
Name the file to include the venue (``dev``, ``test``, or ``prod``) so credentials for each environment are kept separate, e.g. ``registry-auth-prod.txt``.
66
65
67
-
user = {username sent by Engineering Node}
68
-
password = {your password}
66
+
1. Create ``$HOME/.pds/registry-auth-{venue}.txt`` with the credentials provided by the Engineering Node:
Engineering Node (pds-operator@jpl.nasa.gov) will provide you with a config file containing necessary Registry OpenSearch configuration information.
75
+
.. code:: bash
77
76
78
-
On **Linux** and Linux-like Operating Systems:
77
+
chmod 600 $HOME/.pds/registry-auth-{venue}.txt
79
78
80
-
Update this file with your username and password.
81
79
82
-
As needed, update the setting of the environment variables to match the shell you are using.
80
+
Create the Registry Client Environment File
81
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
82
84
-
Place in the secure location created above.
83
+
The Engineering Node will provide a ``registry-client.env`` file with OpenSearch connection settings. Rename it to include the venue (e.g. ``registry-client-prod.env``) before placing it in ``$HOME/.pds/``.
85
84
86
-
On **Windows**:
85
+
**Linux / macOS:**
87
86
88
-
The environment variables noted will need to be set manually through the Windows console.
87
+
1. Open the provided ``registry-client-{venue}.env`` file.
88
+
2. Update the ``user`` and ``password`` fields with your credentials.
89
+
3. Adjust the environment variable export syntax if needed for your shell (``bash``, ``zsh``, etc.).
90
+
4. Place the file in ``$HOME/.pds/``.
89
91
90
-
OpenSearch Connection Configuration File, For Harvest and Registry Manager
The Engineering Node will send you this file, already named using the pattern ``registry-config-{node}-{venue}.xml`` (e.g. ``registry-config-sbn-dev.xml``, ``registry-config-sbn-test.xml``, ``registry-config-sbn-prod.xml``).
102
+
103
+
1. Place the file in ``$HOME/.pds/``.
94
104
95
105
.. note::
96
-
Engineering Node (pds-operator@jpl.nasa.gov) will provide you with the content of the file.
106
+
Contact pds-operator@jpl.nasa.gov if you have not received this file.
107
+
97
108
109
+
Next Steps
110
+
~~~~~~~~~~
98
111
99
-
Run Registry Tools on AWS
100
-
~~~~~~~~~~~~~~~~~~~~~~~~~
112
+
Once setup is complete, proceed to:
101
113
102
-
You can run harvest on AWS, on ECS or EC2 directly.
114
+
- :doc:`Install </install/install>`
115
+
- :doc:`User Tasks </user/tasks>`
103
116
104
-
Run Harvest On EC2
105
-
-------------------
117
+
.. note::
118
+
If you are running Harvest on AWS EC2 or ECS, see :ref:`connection-setup:Additional Setup for AWS` before proceeding.
106
119
107
-
You can run Harvest on EC2, as anywhere else, using the Cognito authentication and configurations described above.
108
120
109
-
However, to be able to access the PDS Registry which is also hosted on AWS, on a different AWS account, you must disable “Private DNS names” in the VPC endpoint of the API gateway, otherwise the PDS Registry API gateway requests will be redirected to your own account and fail.
121
+
Additional Setup for AWS
122
+
************************
110
123
111
-
See the AWS console screenshot, you should have **No** instead of **Yes** here:
124
+
Run Harvest on EC2
125
+
~~~~~~~~~~~~~~~~~~
112
126
113
-
.. image:: _static/images/aws_console_vpc.png
127
+
Harvest on EC2 uses the same Cognito authentication and config files described above.
114
128
115
-
If you need to change that in your AWS account, double check that all your other applications still work.
129
+
If your EC2 instance is on a **different AWS account** than the PDS Registry, you must disable **Private DNS names** on the VPC endpoint for the API gateway. Without this change, API gateway requests are redirected to your own account and will fail.
116
130
131
+
1. In the AWS Console, open the VPC endpoint for the API gateway.
132
+
2. Set **Enable private DNS names** to **No**.
117
133
134
+
.. image:: _static/images/aws_console_vpc.png
118
135
119
-
Run Harest On ECS
120
-
-------------------
136
+
3. Verify that your other applications still function after this change.
121
137
122
-
You can run harvest on ECS, as on EC2 using the Cognito authentication.
123
138
124
-
Alternatively if you run harvest, on ECS, on the same AWS account as the Registry service, you can also configure the connexion to the Registry without Cognito authentication, as follows:
139
+
Run Harvest on ECS
140
+
~~~~~~~~~~~~~~~~~~
125
141
126
-
.. code:: xml
142
+
**Option A — Cognito authentication (cross-account or external):**
0 commit comments