================================
Deploy a Cluster through the API
================================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. _create-cluster-with-api-overview:

Overview
--------

This tutorial manipulates the :doc:`Public API's </core/api>`
automation configuration to deploy a :term:`sharded cluster` that is
owned by another user. The tutorial first creates a new project, then a
new user as owner of the project, and then a sharded cluster owned by
the new user. You can create a script to automate these procedures for
use in routine operations.

.. cond:: cloud

   To perform these steps, you must have sufficient access to |mms|. A
   user with the :authrole:`Project Owner` role has sufficient access.

.. cond:: onprem

   To perform these steps, you must have sufficient access to |mms|. A
   user with the :authrole:`Global Owner` or
   :authrole:`Project Owner` role has sufficient access.

<<<<<<< HEAD
=======
The procedures install a cluster with two :term:`shards <shard>`. Each
shard comprises a three-member :term:`replica set`. The tutorial
installs one |mongos| and three
:term:`config servers <config server>`. Each component of the cluster
resides on its own server, requiring a total of 10 servers.
>>>>>>> (DOCSP-5135): Create MongoDB Agent install page.

The tutorial installs the
:doc:`{+mdbagent+} </tutorial/nav/install-mongodb-agent>` on each
host.

.. _create-cluster-with-api-prerequisites:

Prerequisites
-------------

.. cond:: onprem

   |mms| must have an existing user. If you are deploying the sharded
   cluster on a fresh install of |mms|, you must register the first
   user.

   You must have the URL of the |onprem| Web Server, as set in the
   You must have the |url| of the |onprem| Web Server, as set in the
   ``mmsBaseUrl`` setting of the :doc:`{+magent+} configuration
   file </reference/monitoring-agent>`.

   Provision ten servers to host the components of the :term:`sharded
   cluster`. For server requirements, see the :manual:`Production Notes
   </administration/production-notes>` in the MongoDB manual.

<<<<<<< HEAD
   Each server must provide its
   :doc:`{+aagent+} </tutorial/nav/install-mongodb-agent>` with full
   networking access to the hostnames and ports of the {+aagent+}s on
   all the other servers. Each agent runs the command ``hostname -f``
   to self-identify its hostname and port and report them to |mms|.
=======
   Each server must provide its :doc:`{+aagent+}
   </tutorial/nav/install-mongodb-agent>` with full networking access to
   the hostnames and ports of the {+aagent+}s on all the other servers.
   Each agent runs the command ``hostname -f`` to self-identify its hostname
   and port and report them to |mms|.
>>>>>>> (DOCSP-5135): Create MongoDB Agent install page.

   .. tip::

   To ensure agents can reach each other,
   :doc:`provision the servers using Automation </tutorial/add-servers-automation>`.
   This installs the {+aagent+}s with correct network access. Then use
   this tutorial to reinstall the {+aagent+}s on those machines.

Examples
--------

As you work with the API, you can view examples on the
`GitHub example page <https://github.com/10gen-labs/mms-api-examples/tree/master/automation/>`_.

Procedures
----------

Generate a Public API Key
+++++++++++++++++++++++++

This procedure displays the full API key **just once**. You must record
the API key when it is displayed.

.. note::

   A :term:`Public API key` is different from an :term:`agent API key`.
   A Public API key is associated with a user; an agent API key is
   associated with a project.

.. include:: /includes/steps/generate-public-api-key-for-user.rst

Create the Group and the User through the API
+++++++++++++++++++++++++++++++++++++++++++++

.. include:: /includes/steps/create-group-through-api.rst

Install the {+aagent+} on each Provisioned Server
+++++++++++++++++++++++++++++++++++++++++++++++++++++++

Your servers must have the networking access described in the
:ref:`create-cluster-with-api-prerequisites`.

.. include:: /includes/steps/install-automation-agent-to-provisioned-servers.rst

Deploy the New Cluster
++++++++++++++++++++++

To add or update a deployment, retrieve the :ref:`configuration
document <automation-configuration-sample-entity>`, make changes as
needed, and send the updated configuration though the API to |mms|.

The following procedure deploys an updated automation configuration
through the Public API:

.. include:: /includes/steps/create-cluster-through-api.rst

Next Steps
----------

To make an additional version of MongoDB available in the cluster,
follow the steps in
:doc:`update-mongodb-version-of-deployment-via-api`.
