Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/google-cloud-platform.rst @ 451:938206110483
added object storage
author | Alain Mazy <alain@mazy.be> |
---|---|
date | Fri, 03 Jul 2020 12:52:11 +0200 |
parents | 2922fb1bd65e |
children | a4ed4e883337 |
rev | line source |
---|---|
254 | 1 .. _google: |
2 | |
3 | |
4 Google Cloud Platform plugin | |
5 ============================ | |
6 | |
7 .. contents:: | |
8 | |
255 | 9 |
10 Introduction | |
11 ------------ | |
12 | |
13 Osimis freely provides the `source code | |
449 | 14 <https://hg.orthanc-server.com/orthanc-gcp/file/default/>`__ of a plugin |
361 | 15 to interface Orthanc with the Healthcare API of `Google Cloud Platform |
259 | 16 (GCP) <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ through |
17 `DICOMweb <https://www.dicomstandard.org/dicomweb/>`__. | |
255 | 18 |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
19 This GCP plugin turns Orthanc into a DICOMweb client connected to GCP |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
20 servers, enabling the upload of DICOM images using STOW-RS, the |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
21 querying of the cloud content using QIDO-RS, and the retrieval of |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
22 remote content using WADO-RS. These operations can be possibly |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
23 :ref:`scripted <dicomweb-client>` thanks to the REST API of Orthanc. |
255 | 24 |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
25 Concretely, the role of the GCP plugin is to `manage the credentials |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
26 <https://cloud.google.com/docs/authentication/>`__ to Google Cloud |
255 | 27 Platform. It requires the official :ref:`DICOMweb plugin <dicomweb>` |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
28 to be installed, as all the user interactions are done through the |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
29 latter plugin. As soon as Orthanc is started, the GCP plugin |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
30 automatically acquires then periodically refreshes the access tokens, |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
31 transparently updating the remote :ref:`DICOMweb servers |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
32 <dicomweb-client-config>` that are known to the DICOMweb plugin. The |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
33 access tokens can be derived either from service accounts, or from |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
34 user accounts. |
255 | 35 |
36 This page makes the assumption that you have created a Google Cloud | |
37 Platform project, in which you have enabled the `Healthcare API | |
38 <https://cloud.google.com/healthcare/>`__, and in which you have | |
39 created a `DICOM store | |
40 <https://cloud.google.com/healthcare/docs/how-tos/dicom>`__. | |
41 | |
42 | |
43 | |
44 Compilation | |
45 ----------- | |
46 | |
47 .. highlight:: text | |
48 | |
49 The procedure to compile the GCP plugin is similar of that for the | |
50 :ref:`core of Orthanc <compiling>`. The following commands should work | |
51 on any recent UNIX-like distribution (including GNU/Linux):: | |
52 | |
53 $ mkdir Build | |
54 $ cd Build | |
55 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | |
56 $ make | |
57 | |
58 The compilation produces a shared library | |
259 | 59 ``OrthancGoogleCloudPlatform`` that contains the GCP |
451 | 60 plugin. |
255 | 61 |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
62 Under the hood, the GCP plugin is built on the top of the official |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
63 `Google Cloud Platform C++ Client Libraries |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
64 <https://github.com/googleapis/google-cloud-cpp>`__. |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
65 |
255 | 66 |
451 | 67 Given this plugin is used to interface with a commercial & proprietary |
68 service, pre-compiled Windows/Docker binaries are available only for | |
69 companies who have subscribed for a `support contract <https://www.osimis.io/en/services.html#cloud-plugins>`__ at Osimis. | |
70 | |
255 | 71 |
72 Configuration | |
73 ------------- | |
74 | |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
75 Dependencies |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
76 ^^^^^^^^^^^^ |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
77 |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
78 As explained above, the GCP plugin requires Orthanc (with version |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
79 above 1.5.4), and the :ref:`official DICOMweb plugin <dicomweb>` to be |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
80 installed (with version above 1.0). All the communications with Google |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
81 Cloud Platform are done using the DICOMweb plugin, and the |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
82 responsibility of the GCP plugin is to aquire and periodically refresh |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
83 the access tokens whose lifetime is limited. |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
84 |
255 | 85 |
86 Common parameters | |
87 ^^^^^^^^^^^^^^^^^ | |
88 | |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
89 There are some common parameters to be set. Firstly, the ``Plugins`` |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
90 :ref:`configuration option <configuration>` of Orthanc must contain |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
91 the path that contains the ``OrthancGoogleCloudPlatform`` shared |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
92 library. |
255 | 93 |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
94 Secondly, obtaining the access tokens for Google Cloud Platform |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
95 necessitates a sequence of HTTPS requests. As a consequence, the |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
96 Orthanc configuration must specify how the authenticity of the Google |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
97 servers is verified. You have two possibilities to that end: |
255 | 98 |
99 1. Disabling the verification of the remote servers (**not recommended | |
100 in production**). This is done by setting option ``HttpsVerifyPeers`` | |
101 to ``false``. | |
102 | |
103 2. Providing a list of `trusted Certificate Authorities (CA) | |
104 <https://curl.haxx.se/docs/sslcerts.html>`__ to the HTTPS client | |
105 that is internally used by Orthanc (namely, `cURL | |
106 <https://en.wikipedia.org/wiki/CURL>`__). This is done by properly | |
299 | 107 setting ``HttpsCACertificates`` option, so that it points to a file |
255 | 108 containing a store of CA certificates. Depending on your operating |
109 system, this file can be found as follows: | |
110 | |
111 * On Debian-based system, the standard file | |
112 ``/etc/ssl/certs/ca-certificates.crt`` can be used. | |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
113 * On other systems (including Microsoft Windows), the cURL project |
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
114 provides `CA certificates |
255 | 115 <https://curl.haxx.se/docs/caextract.html>`__ that are extracted |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
116 from Mozilla. |
255 | 117 |
259 | 118 Note that to debug HTTPS communications, you have the possibility of |
119 setting the ``HttpVerbose`` configuration option of Orthanc to | |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
120 ``true``. It can also be useful to run Orthanc in ``--verbose`` mode |
259 | 121 (check out :ref:`this page <log>`). |
255 | 122 |
254 | 123 |
124 | |
255 | 125 Service account |
126 ^^^^^^^^^^^^^^^ | |
127 | |
128 As explained on the `Google documentation | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
129 <https://cloud.google.com/docs/authentication>`__, *"a service account |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
130 is a Google account that represents an application, as opposed to |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
131 representing an end user"*. This is presumably the most common |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
132 situation in the case of Orthanc. |
255 | 133 |
134 You first have to `create a service account | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
135 <https://cloud.google.com/docs/authentication/getting-started>`__ for |
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
136 your application. This will produce a JSON file (say, |
255 | 137 ``dicom-osimis.json``) that you have to store securely on the server |
138 that will run Orthanc. | |
139 | |
140 .. highlight:: json | |
141 | |
142 Secondly, you have to modify the :ref:`Orthanc configuration | |
143 <configuration>` in order to provide the GCP plugin with your service | |
144 account file and with the parameters of your `DICOM store | |
145 <https://cloud.google.com/healthcare/docs/how-tos/dicom>`__. Here is a | |
256 | 146 sample, minimalist configuration of Orthanc:: |
255 | 147 |
148 { | |
149 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt", | |
150 "Plugins" : [ "." ], | |
151 "GoogleCloudPlatform" : { | |
152 "Accounts": { | |
153 "my-google" : { | |
154 "Project" : "osimis-test", | |
155 "Location" : "europe-west2", | |
156 "Dataset" : "test", | |
157 "DicomStore" : "dicom", | |
158 "ServiceAccountFile" : "dicom-osimis.json" | |
159 } | |
160 } | |
161 } | |
162 } | |
163 | |
164 | |
165 In this example, once the GCP plugin has succeeded to authenticate | |
166 using the service account, the DICOMweb plugin will provide access to | |
167 the cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the | |
168 REST API of Orthanc. | |
169 | |
170 | |
171 User account | |
172 ^^^^^^^^^^^^ | |
173 | |
174 User account is an alternative to service account, and can be used | |
175 *"when the application needs to access resources on behalf of an end | |
176 user"* (check out the `Google documentation | |
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
177 <https://cloud.google.com/docs/authentication/end-user>`__). |
255 | 178 |
179 .. highlight:: json | |
180 | |
181 The easiest way of setting up a user account is through the `gcloud | |
182 command-line tool <https://cloud.google.com/sdk/gcloud/>`__. | |
256 | 183 `Google's quick-starts |
255 | 184 <https://cloud.google.com/sdk/docs/quickstarts>`__ explain how to |
185 initialize the environment depending on your operating system (check | |
186 out the "Initialize the SDK" sections, which essentially boil down to | |
187 calling ``gcloud init``). | |
188 | |
189 | |
190 .. highlight:: bash | |
191 | |
192 Once the ``gcloud init`` command-line has been invoked, you can | |
259 | 193 extract credentials to be used by Orthanc by typing the following |
194 command:: | |
255 | 195 |
196 $ gcloud auth print-access-token --format json | |
197 | |
198 | |
199 .. highlight:: json | |
200 | |
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
201 This command generates a JSON file containing all the required |
255 | 202 information, that can be written to a file (say, |
256 | 203 ``dicom-user.json``). Given this file, here is a sample, minimalist |
255 | 204 configuration of Orthanc:: |
205 | |
206 { | |
207 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt", | |
208 "Plugins" : [ "." ], | |
209 "GoogleCloudPlatform" : { | |
210 "Accounts": { | |
211 "my-google" : { | |
212 "Project" : "osimis-test", | |
213 "Location" : "europe-west2", | |
214 "Dataset" : "test", | |
215 "DicomStore" : "dicom", | |
216 "AuthorizedUserFile" : "dicom-osimis.json" | |
217 } | |
218 } | |
219 } | |
220 } | |
221 | |
222 In this example, once the GCP plugin has succeeded to authenticate | |
223 using the user account, the DICOMweb plugin will provide access to the | |
224 cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the REST | |
225 API of Orthanc. | |
226 | |
227 | |
228 .. highlight:: bash | |
229 | |
230 Note that only 3 fields in the JSON file produced by the ``gcloud auth | |
259 | 231 print-access-token`` command are required: ``client_id``, |
232 ``client_secret``, and ``refresh_token``. Instead of using the full | |
233 JSON file, you can extract only these fields, e.g. using the `jq | |
255 | 234 <https://stedolan.github.io/jq/>`__ command-line tool:: |
235 | |
236 $ gcloud auth print-access-token --format json | jq '{ AuthorizedUserClientId: .client_id, AuthorizedUserClientSecret:.client_secret, AuthorizedUserRefreshToken:.refresh_token }' | |
237 { | |
238 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com", | |
239 "AuthorizedUserClientSecret": "ZmssLNXXXXXX", | |
240 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX" | |
241 } | |
242 | |
243 | |
244 .. highlight:: json | |
245 | |
259 | 246 These fields can then be copied/pasted as follows in order to create a |
247 configuration for Orthanc that is equivalent to the one using the | |
248 separate JSON file:: | |
255 | 249 |
250 { | |
251 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt", | |
252 "Plugins" : [ "." ], | |
253 "GoogleCloudPlatform" : { | |
254 "Accounts": { | |
255 "my-google" : { | |
256 "Project" : "osimis-test", | |
257 "Location" : "europe-west2", | |
258 "Dataset" : "test", | |
259 "DicomStore" : "dicom", | |
260 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com", | |
261 "AuthorizedUserClientSecret": "ZmssLNXXXXXX", | |
262 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX" | |
263 } | |
264 } | |
265 } | |
266 } | |
259 | 267 |
268 | |
269 Advanced options | |
270 ^^^^^^^^^^^^^^^^ | |
271 | |
272 .. highlight:: json | |
273 | |
274 Some advanced configuration options are available as well, as | |
275 summarized in this excerpt:: | |
276 | |
277 { | |
278 ... | |
279 // In seconds, must be large enough to send/receive your largest studies | |
280 // using WADO or STOW, depending on the speed of your Internet connection | |
281 "HttpTimeout" : 600, | |
282 | |
283 "GoogleCloudPlatform" : { | |
284 ... | |
285 // Path to the URL of the GCP services | |
286 "BaseUrl" : "https://healthcare.googleapis.com/v1beta1/" | |
287 } | |
288 } |