Skip to content

Latest commit

 

History

History
228 lines (162 loc) · 12.1 KB

chapter-smartproxy.asciidoc

File metadata and controls

228 lines (162 loc) · 12.1 KB

Smart Proxy

{inrmonly}

Introduction

Default is Polling

Typically an organization runs a single {pro} instance to proxy external components as well as host internally produced components. When a build is running against this instance, it will look for any new components in the proxied remote repositories. This adds additional network traffic that in many cases will just be a response from the remote server indicating that there are no changes.

This polling approach is fine for smaller deployments. It will not result in immediately updated components as soon as they become available upstream. In distributed teams with multiple {pro} instances, this delay can result in build failures and delays. The only way you are going to achieve that everything is up to date is by setting expiration times to zero and constantly polling.

Smart Proxy Introduces Publish-Subscribe

Increasingly, {pro} is used in globally distributed teams or used by projects that span multiple organizations. In many cases, it is advisable for each physical location to host its own {pro} instance. This local instance hosts its own components and proxies the other servers.

An example deployment scenario is displayed in Deployment Scenario for a Smart Proxy Use Case. Using the traditional polling approach, specifically when used with snapshot repositories, can result in significant traffic and a performance hit for all involved servers.

The 'Smart Proxy' feature replaces this constant polling approach with a 'Publish/Subscribe'-based messaging approach between repository manager instances sharing a mutual trust. Once a component is published to a repository a message is sent to all subscribing in the smart proxy message queue that details the availability of new component. The subscribers are therefore immediately aware of any new deployment and can provide these components without having to poll the publishing server.

The result is a significantly improved performance due to nearly immediate availability of upstream component information directly in the downstream repository managerinstances.

Enabling Smart Proxy Publishing

In order to enable the smart proxy feature on your {pro} instance, you need to navigate to the global 'Smart Proxy' configuration screen. It is available in the left-hand navigation in the 'Enterprise' section. Selecting 'Smart Proxy' will show you the configuration screen displayed in Global Configuration for Smart Proxy.

smart proxy global config
Figure 1. Global Configuration for Smart Proxy

The 'Network Settings' section allows you to enable the smart proxy server with a checkbox. This will need to be enabled on all servers that publish events in the smart proxy network, while servers that act only as subscribers can leave this option unchecked.

In addition, you can configure the address and port where the publishing server will be available. The default address of 0.0.0.0 will cause the proxy to listen on all addresses. The default port number of 0 will trigger usage of a random available port number for connection listening. If a random port is used, it will be chosen when the server (re)starts.

With the 'Advertised URI' field it is possible to configure a specific address to be broadcasted by the proxy to the subscribing smart proxy clients enabling, e.g., usage of a publicly available fully qualified hostname, including the domain or also just the usage of an externally reachable IP number.

Important
It is important to configure the ports in the repository manager and any firewall between the servers to allow the direct socket connection between the servers and to avoid using random ports.

The 'Status' field below the form will show the current status of the smart proxy including the full address and port.

The 'Public Key' field displays the key identifying this server instance. It is automatically populated with the certificate associated with the public/private key pair that is generated when the server is first run.

Tip
The key is stored in sonatype-work/nexus/conf/keystore/private.ks and identifies this server. If you copy the sonatype work folder from one server to another as part of a migration or a move from testing to staging or production you will need to ensure that keys are not identical between multiple servers. To get a new key generated, simply remove the keystore file and restart the repository manager.

Establishing Trust

The servers publishing as well as subscribing to events identify themselves with their public key. This key has to be registered with the other servers in the 'Trusted Certificates' section of the 'Smart Proxy' configuration screen.

To configure two repository managers as trusted smart proxies, you copy the public key from the certificate of the other server in the 'Trusted Certificates' configuration section by adding a new trusted certificate with a meaningful description as displayed in Copying a Certificate and Adding a Trusted Certificate.

smart proxy copy certificate
Figure 2. Copying a Certificate
smart proxy add certificate
Figure 3. Adding a Trusted Certificate

All of the key generation and certificates related to the trust management is handled by the repository manager itself. No external configuration or usage of external keys is necessary.

Repository Specific Smart Proxy Configuration

Once Smart Proxy has been configured and enabled as previously described, you have to configure which repositories contents should be proxied more efficiently between the servers. This is done in the 'Repositories' administration interface in a separate configuration tab titled 'Smart Proxy', which allows you to configure repository-specific details as compared to server wide details described above.

On the publishing repository manager you have to enable smart proxy on the desired hosted, virtual or proxy repositories in the repository configuration. This is accomplished by selecting the 'Publish Updates' checkbox in the 'Publish' section of the 'Smart Proxy' configuration for a specific repository as displayed in Smart Proxy Settings for a Hosted Repository and pressing save.

smart proxy repo list hosted
Figure 4. Smart Proxy Settings for a Hosted Repository

On the repository manager subscribing to the publishing server you have to create a new proxy repository to expose the proxied components. The smart proxy configuration for this repository displayed in Smart Proxy Settings for a Proxy Repository allows you to activate the 'Receive Updates' checkbox in the 'Subscribe' configuration section. With a working trust established between the publishing and subscribing servers the Smart Proxy configuration of the proxy repository on the subscribing repository manager will display connection status.

smart proxy repo list proxy
Figure 5. Smart Proxy Settings for a Proxy Repository

Smart Proxy Security and Messages

Smart Proxy messages are started with an initial handshake via HTTP or HTTPS. The protocol chosen is determined by the URL defined in the proxy repository configuration in the 'Remote Storage Location'. For increased security we suggest to use HTTPS, even for internal repository URLs. This handshake allows the two server to exchange their keys and confirm that they are configured with a valid trust relationship to communicate. After a successful handshake, messages are sent in the middleware layer and are all sent via SSL encrypted messages.

The following events are broadcasted via Smart Proxy.

  • a new component has been deployed

  • a component has been deleted

  • a component has been changed

  • repository cache or a part of it has been cleared

  • Smart Proxy publishing has been disabled

On the recipient side this will cause the changes to be applied, mimicking what happened on the publisher. If Smart Proxy is disabled the subscription will be stopped.

Example Setup

The deployment scenario displayed in Deployment Scenario for a Smart Proxy Use Case is a typical use case for Smart Proxy. Component development is spread out across four distributed teams located in New York, London, Bangalore and San Jose. Each of the teams has a repository manager instance deployed in their local network to provide the best performance for each developer team and any locally running continuous integration server and other integrations

smart proxy scenario
Figure 6. Deployment Scenario for a Smart Proxy Use Case

When the development team in New York does a commit to their component build, a continuous integration server deploys a new component snapshot version to the 'Nexus 1' instance.

With smart proxy enabled, this deployment is immediately followed by notifications, sent to the trusted smart proxy subscribers in 'Nexus 2', 'Nexus 3', and 'Nexus 4'. These are collocated with the developers in London, Bangalore, and San Jose and can be configured to immediately fetch the new components available. At a minimum they will know about the availability of new component versions without the need to poll 'Nexus 1' repeatedly, therefore, keeping performance high for everyone.

When a user of 'Nexus 2', 3 or 4 build a component that depends on a snapshot version of the component from 'Nexus 1', smart proxy guarantees that the latest version published to 'Nexus 1' is used.

To configure smart proxy between these servers for the snapshots repository you have to

  1. add the public key of 'Nexus 1' as trusted certificate to 'Nexus 2', 3 and 4

  2. add the public keys of 'Nexus 2', 3 and 4 as trusted certificate to 'Nexus 1'

  3. enable smart proxy publishing on the snapshot repository on 'Nexus 1'

  4. set up new proxy repositories to proxy the 'Nexus 1' snapshot repository on 'Nexus 2', 3 and 4

  5. enable smart proxy subscription on the new proxy repositories

  6. optionally enable prefetching of components

  7. add the new proxy repositories to the public group on 'Nexus 2', 3 and 4

With this setup, any snapshot deployment from the New York team on 'Nexus 1' is immediately available to the development team in London, Bangalore, and San Jose.

Advanced Configuration

Typically smart proxy is configured in the dedicated user interfaces provided and described earlier in this chapter. More fine grained and advanced configuration is exposed in the capabilities administration documented in [capabilities].

Specficically the following capabilities for the core smart proxy features are automatically created and maintained.

Smart Proxy: Identity

Provides the unique identity for the repository manager.

Smart Proxy: Messaging

Provides the core messaging facilities for smart proxy.

Smart Proxy: Trust

Configures a trust relationsship with a remote node.

Smart Proxy: Secure Connector

Secures the connection using identity and trust.

In addition you can find one smart proxy capability for each repository configured to be publish or subscribe updates with Smart Proxy.

Smart Proxy: Publish

Configures publishing updates to a specific repository via smart proxy.

Smart Proxy: Subscribe

Configures subscribing to updates for a specific proxy repository. This capability exposes the additional setting 'Delete' in the 'Settings' tab. If deletion is enabled, any component deletions in the publishing repository is also carried out in the subscribing repositories. The 'Preemptive Fetch' flag allows you to enable a download of components to the susbscribing proxy repository prior to any component requests received by it. The default behaviour with preemptive fetch disabled only publishes the fact that new components are available from the publishing repository.

Tip
A series of videos demonstrating Smart Proxy is available on the Nexus community site.