SmartDataCenter (SDC) is an open-source cloud management platform, optimized to deliver next generation, container-based, service-oriented infrastructure across one or more datacenters. With an emphasis on ease of installation and operation, SDC is proven at scale: it is the software that runs the Joyent public cloud and powers numerous private clouds at some of the world's largest companies.

This repo provides documentation for the overall SDC project and pointers to the other repositories that make up a complete SDC deployment. See the repository list.

To report bugs or request features, submit issues to the joyent/sdc project. For additional resources, you can visit the Joyent Developer Center.

A SmartDataCenter installation consists of two or more servers. All servers run SmartOS. One server acts as the management server, the headnode (HN), which houses the initial set of core services that drive SDC. The remainder are compute nodes (CNs) which run instances (virtual machines).

SDC features:

• SmartOS zones provides high performance container virtualization. KVM support on top of zones means secure full Linux and Windows guest OS support.
• RESTful API and CLI tooling for customer self-service
• Complete operations portal (web GUI)
• Robust and observable service oriented architecture (implemented primarily in Node.js)
• Automated USB key installation

SDC consists of the following components:

• A public API for provisioning and managing instances (virtual machines), networks, users, images, etc.
• An operator portal.
• A set of private APIs.
• Agents running in the global zone of CNs for management and monitoring.

For more details, see:

• The overview of SDC in the SDC operator documentation.
• SmartDataCenter Architecture for overall architecture.
• SmartDataCenter Reference for an overview of each component.

Community discussion about SmartDataCenter happens in two main places:

• The sdc-discuss mailing list. Once you subscribe to the list, you can send mail to the list address: [email protected]. The mailing list archives are also available on the web.

• In the #smartos IRC channel on the Freenode IRC network.

You can also follow @SmartDataCenter on Twitter for updates.

An easy way to try SmartDataCenter is by downloading a Cloud on a Laptop (CoaL) build. This is a VMware virtual appliance providing a full SDC headnode for development and testing.

Minimum requirements: practically speaking, a good CoaL experience requires a Mac with at least 16GB RAM and SSD drives. Currently, all core team members using CoaL are on Macs with VMware Fusion. For Linux and Windows VMware Workstation should work, but has not recently been tested.

See CoaL Setup for a thorough walkthrough.

1. Start the download of the latest CoaL build. The tarball is over 2GB.

   curl -C - -O https://us-east.manta.joyent.com/Joyent_Dev/public/SmartDataCenter/coal-latest.tgz

2. Install VMware, if you haven't already.

   • Mac: VMware Fusion 4, 5 or 7.
   • Windows or Linux: VMware Workstation.

3. Configure VMware virtual networks for CoaL's "external" and "admin" networks. This is a one time configuration for a VMware installation.

   1. Launch VMware at least once after installing VMware.

   2. Download and run the following setup script from this repository to configure VMware's networking.

      • Mac:

        sudo ./tools/coal-mac-vmware-setup

      • Linux: not yet written.

      • Windows:

        tools\coal-windows-vmware-setup.bat
        

4. Unpack the CoaL build that you downloaded in step 1.

   • Mac:

     $ tar xvzf coal-latest.tgz
     x root.password.20140926t231701z
     x coal-release-20140918-20140927T030204Z-gec168e5-4gb.vmwarevm/
     x coal-release-20140918-20140927T030204Z-gec168e5-4gb.vmwarevm/zpool.vmdk
     x coal-release-20140918-20140927T030204Z-gec168e5-4gb.vmwarevm/USB-headnode.vmxf
     x coal-release-20140918-20140927T030204Z-gec168e5-4gb.vmwarevm/USB-headnode.vmsd
     x coal-release-20140918-20140927T030204Z-gec168e5-4gb.vmwarevm/4gb.img
     ...

5. Run CoaL on VMware:

   • Mac: 'open'ing the folder will start VMware and load the appliance:

     open coal-master-<build_id>-<git_sha1_hash>-4gb.vmwarevm

6. Boot the headnode:

   1. When you are prompted with the GRUB menu press the "down" arrow.

   2. Select the "Live 64-bit" option and press 'c' to enter the command line for GRUB. By default, the OS will be redirect the console to be ttyb which is fine for production but needs to be changed for COAL. While in the command line:

       grub> variable os_console vga
      

   3. Press 'ESC' to get back to the GRUB menu.

   4. Boot "Live 64-bit" by pressing 'enter'.

7. Configure the headnode. The setup process, in short, is as follows:

   • On first boot, you are interactively prompted for minimal configuration (e.g. datacenter name, company name, networking information). Here is a guide for answering these questions:

     Setting	Value	Notes
     Company Name	Joyent, Inc.	Can substitute with your choice
     Region of Datacenter	west	Can substitute with your choice
     Name of Datacenter	coal	Can substitute with your choice
     Location of Datacenter	San Francisco, CA	Can substitute with your choice
     'admin' interface	2	The second NIC is set up as the admin network by the COAL networking script
     (admin) headnode IP address	10.99.99.7	Must use this value
     (admin) headnode netmask:	↵	Use Default
     (admin) Zone's starting IP address:	↵	Use Default
     Add external network now? (Y/n)	Y	Must use this value
     'external' interface	1	The first NIC is set up as the external network by the COAL networking script
     (external) headnode IP address	10.88.88.200	Must use this value
     (external) headnode netmask:	↵	Use Default
     (external) gateway IP address:	10.88.88.2	Must use this value
     (external) network VLAN ID	↵	Use Default, the external network is not on a VLAN in COAL
     Starting Provisionable IP address for external Network	↵	Use Default or 10.88.88.20
     Ending Provisionable IP address for external Network	↵	Use Default or 10.88.88.254
     Default gateway IP address	↵	Use Default
     Primary DNS Server	↵	Use Default
     Secondary DNS Server	↵	Use Default
     Head node domain name	joyent.us	Can substitute with your choice
     DNS Search Domain	joyent.us	Can substitute with your choice
     NTP Server IP Address	↵	Use Default
     root password	root	Can substitute with your choice
     admin password	joypass123	Can substitute with your choice
     Administrator's email	↵	Use Default
     Support email	↵	Use Default
     Enable telemetry	"true" or "false"	Can use your choice

     The configuration is saved and the server reboots.

   • On reboot, all SDC services are installed. Expect this to take around 15-20 minutes.

8. After setup is complete you should be able to SSH into your CoaL on the "admin" network. Example:

   ssh [email protected]  # password 'root'

For just a taste run svcs to see running SMF services. Run vmadm list to see a list of current VMs (SmartOS zones). Each SDC service runs in its own zone. See the SDC operator guide.

A SmartDataCenter server runs SmartOS, which is a "live image". That means that it boots from a USB key. Installing SDC involves writing a "USB" build to a physical USB key, inserting the key and booting the server from that key. To install SDC, first obtain the latest release USB build.

For SDC development only, the minimum server hardware is:

• 8 GB USB flash drive
• Intel Processors with VT-x and EPT support (all Xeon since Nehalem).
• 16 GB RAM
• 6 GB available storage. Hardware RAID is not recommended. SDC will lay down a ZFS ZPOOL across all available disks on install. You'll want much more storage if you're working with images and instances.

If setting up a SmartDataCenter pilot then you'll want to review the SDC7 Installation Prerequisites which include IPMI and at least 10 gigabit Ethernet. The supported hardware components for SmartOS are described in the SmartOS Hardware Requirements. Joyent certified hardware for SmartDataCenter are all in the Joyent Manufacturing Database.

Download the USB key image:

curl -C - -O https://us-east.manta.joyent.com/Joyent_Dev/public/SmartDataCenter/usb-latest.tgz

Once you have downloaded an image, you will need to write it to a USB key, boot the machine with it, and follow the install prompts. See the installing SDC 7 and install checklist documents for information.

After installation, you will probably want to perform some additional configuration. The most common of these include:

• Adding external nics to the imgapi and adminui zones to give them internet access. This enables simple import of VM images.
• Provision a cloudapi zone to allow users to create and administer their VMs without an operator.

See the post-installation configuration documentation for the complete list.

SDC is composed of several pre-built components:

• A SmartOS platform image. This is a slightly customized build of vanilla SmartOS for SDC.
• Virtual machine images for SDC services (e.g. imgapi, vmapi, adminui), which are provisioned as VMs at install time.
• Agents, which are bundled into a single package that can then be installed into the global zone of Compute Nodes.

Each component is built separately and then all are combined into CoaL and USB builds (see the preceding sections) via the sdc-headnode repository. Built components are typically stored in a Manta object store, e.g. Joyent's public Manta, and pulled from there. For example, Joyent's core builds push to /Joyent_Dev/public/builds in Joyent's public Manta in us-east-1 (https://us-east.manta.joyent.com/).

You can build your own CoaL and USB on Mac or SmartOS (see the sdc-headnode README). However, all other SDC components must be built using a running SDC (e.g. on the Joyent Cloud or in a local CoaL). See the building document for details on building each of the SDC components.

To report bugs or request features, submit issues to the joyent/sdc project. If you're contributing code, make a pull request to the appropriate repo (see the repo overview). If you're contributing something substantial, you should first contact developers on the sdc-discuss mailing list (subscribe, archives) or #smartos on the Freenode IRC network.

For help or issues with the Joyent Cloud or production Manta service, contact Joyent Cloud customer support instead.

SDC repositories follow the Joyent Engineering Guidelines. Notably:

• The #master branch should be first-customer-ship (FCS) quality at all times. Don't push anything until it's tested.
• All repositories should be make check clean at all times.
• All repositories should have tests that run cleanly at all times.

make check checks both JavaScript style and lint. Style is checked with jsstyle. The specific style rules are somewhat repo-specific. Style is somewhat repo-specific. See the jsstyle configuration file or JSSTYLE_FLAGS in Makefiles in each repo for exceptions to the default jsstyle rules.

Lint is checked with javascriptlint. (Don't conflate lint with style! There are gray areas, but generally speaking, style rules are arbitrary, while lint warnings identify potentially broken code. Repos sometimes have repo-specific lint rules -- look for "tools/jsl.web.conf" and "tools/jsl.node.conf" for per-repo exceptions to the default rules.

SmartDataCenter is very opinionated about how to architect a cloud. These opinions are the result of many years of deploying and debugging the Joyent Cloud. Design principles include the following:

• A VM's primary storage should be a local disk, not over the network -- this avoids difficult to debug performance pathologies.
• Communication between internal APIs should occur in its own control plane (network) that is separate from the customer networks. Avoid communicating over the open Internet if possible.
• A provisioned VM should rely as little as possible on SDC services outside of the operating system for its normal operation.
• Installation and operation should require as little human intervention as possible.

The goals behind the design of SDC services include:

• All parts of the stack should be observable.
• The state of the running service should be simple to obtain.
• The internals of the system should make it straightfoward to debug from a core file (from a crash or taken from a running process using gcore(1))
• Services should be RESTful and accept JSON unless there is a compelling reason otherwise.
• Services should avoid keeping state and should not assume that there is only one instance of that service running. This allows multiple instances of a service to be provisioned for High Availability.
• Node.js and C should be used for new services.

SmartDataCenter uses SmartOS as the host OS. The SmartOS hypervisor provides both SmartOS zone (container) and KVM virtualization.

Joyent's open-source Manta project is an HTTP-based object store with built-in support to run arbitrary programs on data at rest (i.e., without copying data out of the object store). Manta runs on and integrates with SmartDataCenter.

SmartDataCenter is licensed under the Mozilla Public License version 2.0. SmartOS is licensed separately.