---
layout: default
navsection: installguide
title: InternalURLs and ExternalURL
...
{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
The Arvados configuration is stored at @/etc/arvados/config.yml@. See the "Configuration reference":config.html for more detail.
The @Services@ section lists a number of Arvados services, each with an @InternalURLs@ and/or @ExternalURL@ configuration key. This document explains the precise meaning of these configuration keys, and how they are used by the Arvados services.
Generally speaking, the keys under @InternalURLs@ are the endpoints where the service should be listening, and reachable from other hosts inside the Arvados cluster. The @ExternalURL@ value is the URL that the service advertises as its own URL. The @ExternalURL@ is the address where the service should be reachable from outside the Arvados cluster.
Because many of the Arvados services live behind a reverse proxy (e.g. Nginx as used in this guide), configuring the reverse proxy and the @InternalURLs@ and @ExternalURL@ values must be done in concert.
We'll walk through a number of examples to explain in more detail.
h2. Keep-balance
Consider this section for the @Keep-balance@ service:
{% codeblock as yaml %}
Keepbalance:
InternalURLs:
"http://ClusterID.example.com:9005/": {}
{% endcodeblock %}
@Keep-balance@ has an API endpoint, but it is only used to expose "Prometheus":https://prometheus.io metrics.
There is no @ExternalURL@ key because @Keep-balance@ does not have an Arvados API, no Arvados services need to connect to @Keep-balance@.
The value for @InternalURLs@ tells the @Keep-balance@ service to start up and listen on port 9005, if it is started on a host where @ClusterID.example.com@ resolves to a local IP address. If @Keep-balance@ is started on a machine where the @ClusterID.example.com@ hostname does not resolve to a local IP address, it would refuse to start up, because it would not be able to find a local IP address to listen on.
It is also possible to use IP addresses in @InternalURLs@, for example:
{% codeblock as yaml %}
Keepbalance:
InternalURLs:
"http://127.0.0.1:9005/": {}
{% endcodeblock %}
In this example, @Keep-balance@ would start up and listen on port 9005 at the @127.0.0.1@ IP address. Prometheus would only be able to access the @Keep-balance@ metrics if it could reach that IP and port, e.g. if it runs on the same machine.
Finally, it is also possible to listen on all interfaces, for example:
{% codeblock as yaml %}
Keepbalance:
InternalURLs:
"http://0.0.0.0:9005/": {}
{% endcodeblock %}
In this case, @Keep-balance@ will listen on port 9005 on all IP addresses local to the machine.
h2. Keepstore
Consider this section for the @Keepstore@ service:
{% codeblock as yaml %}
Keepstore:
InternalURLs:
"http://keep0.ClusterID.example.com:25107": {}
"http://keep1.ClusterID.example.com:25107": {}
{% endcodeblock %}
There is no @ExternalURL@ key because @Keepstore@ is only accessed from inside the Arvados cluster. For access from outside, all traffic goes via @Keepproxy@.
When @Keepstore@ is installed on the host where @keep0.ClusterID.example.com@ resolves to a local IP address, it will listen on port 25107 on that IP address. Likewise on the @keep1.ClusterID.example.com@ host. On all other systems, @Keepstore@ will refuse to start.
h2. Keepproxy
Consider this section for the @Keepproxy@ service:
{% codeblock as yaml %}
Keepproxy:
ExternalURL: https://keep.ClusterID.example.com
InternalURLs:
"http://localhost:25107": {}
{% endcodeblock %}
The @ExternalURL@ advertised is @https://keep.ClusterID.example.com@. The @Keepproxy@ service will start up on @localhost@ port 25107, however. This is possible because we also configure Nginx to terminate SSL and sit in front of the @Keepproxy@ service:
upstream keepproxy {
server 127.0.0.1:25107;
}
server {
listen 443 ssl;
server_name keep.ClusterID.example.com;
proxy_connect_timeout 90s;
proxy_read_timeout 300s;
proxy_set_header X-Real-IP $remote_addr;
proxy_http_version 1.1;
proxy_request_buffering off;
proxy_max_temp_file_size 0;
ssl_certificate /YOUR/PATH/TO/cert.pem;
ssl_certificate_key /YOUR/PATH/TO/cert.key;
# Clients need to be able to upload blocks of data up to 64MiB in size.
client_max_body_size 64m;
location / {
proxy_pass http://keepproxy;
}
}
server {
listen 443 ssl;
server_name workbench.ClusterID.example.com;
ssl_certificate /YOUR/PATH/TO/cert.pem;
ssl_certificate_key /YOUR/PATH/TO/cert.key;
root /var/www/arvados-workbench/current/public;
index index.html;
passenger_enabled on;
# If you're using RVM, uncomment the line below.
#passenger_ruby /usr/local/rvm/wrappers/default/ruby;
# `client_max_body_size` should match the corresponding setting in
# the API.MaxRequestSize and Controller's server's Nginx configuration.
client_max_body_size 128m;
}
server {
# This configures the Arvados API server. It is written using Ruby
# on Rails and uses the Passenger application server.
listen localhost:8004;
server_name localhost-api;
root /var/www/arvados-api/current/public;
index index.html index.htm index.php;
passenger_enabled on;
# If you are using RVM, uncomment the line below.
# If you're using system ruby, leave it commented out.
#passenger_ruby /usr/local/rvm/wrappers/default/ruby;
# This value effectively limits the size of API objects users can
# create, especially collections. If you change this, you should
# also ensure the following settings match it:
# * `client_max_body_size` in the previous server section
# * `API.MaxRequestSize` in config.yml
client_max_body_size 128m;
}
# This is the port where nginx expects to contact arvados-controller.
upstream controller {
server localhost:8003 fail_timeout=10s;
}
server {
# This configures the public https port that clients will actually connect to,
# the request is reverse proxied to the upstream 'controller'
listen 443 ssl;
server_name ClusterID.example.com;
ssl_certificate /YOUR/PATH/TO/cert.pem;
ssl_certificate_key /YOUR/PATH/TO/cert.key;
# Refer to the comment about this setting in the passenger (arvados
# api server) section of your Nginx configuration.
client_max_body_size 128m;
location / {
proxy_pass http://controller;
proxy_redirect off;
proxy_connect_timeout 90s;
proxy_read_timeout 300s;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-External-Client $external_client;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Real-IP $remote_addr;
}
}