Remove references to internal CEP/SCF stuff

docs/source/index.rst

@@ -75,6 +75,7 @@ Installing The PaaSTA Infrastructure
 .. toctree::
    :maxdepth: 2
 
+   soa_configs
    installation/getting_started
 
 

docs/source/installation/getting_started.rst

@@ -19,33 +19,8 @@ description and configuration of what services exist and how they should be
 deployed and monitored.
 
 This directory needs to be deployed globally in the same location to every
-server that runs any PaaSTA component.
-
-PaaSTA reads particular config files for each service in the soa-configs
-directory. There is one folder per service. Here is an example tree::
-
-  soa-configs
-  ├── web
-  │   ├── deploy.yaml
-  │   ├── marathon-dev.yaml
-  │   ├── marathon-prod.yaml
-  │   ├── monitoring.yaml
-  │   ├── service.yaml
-  │   └── smartstack.yaml
-  ├── api
-  │   ├── deploy.yaml
-  │   ├── marathon-dev.yaml
-  │   ├── marathon-prod.yaml
-  │   ├── monitoring.yaml
-  │   ├── service.yaml
-  │   └── smartstack.yaml
-  ...
-
-See the `soa-configs documentation <yelpsoa-configs>`_ for more information
-about the structure and contents of these files.
-
-For more information about why we chose this method of config distribution,
-watch `this talk on Yelp's soa-config and how it is used <https://vimeo.com/141231345>`_.
+server that runs any PaaSTA component. See the
+`dedicated documentation <../soa_configs.html>`_ on how to build your own ``soa-configs``.
 
 Docker and a Docker Registry
 ----------------------------

docs/source/monitoring/check_classic_service_replication.rst

@@ -8,7 +8,7 @@ in yelpsoa-configs.
 Monitoring.yaml
 ===============
 
-`yelpsoa-configs (CEP 319) <https://docs.google.com/a/yelp.com/document/d/1ZBg5ykniRU30UXj4YcsKfmmnuegQbtR2VuqCAIGi-50/view#>`_ houses a file called monitoring.yaml whose keys are exposed through service_configuration_lib. You can use it to specify information relevant to monitoring for your service, such as who is responsible for the service, who to contact when it has problems, and even what to look for to ensure it stays up.
+The `soa-configs <https://github.com/Yelp/service_configuration_lib>`_ house a file called monitoring.yaml whose keys are exposed through service_configuration_lib. You can use it to specify information relevant to monitoring for your service, such as who is responsible for the service, who to contact when it has problems, and even what to look for to ensure it stays up.
 
 Available Keys
 --------------
@@ -17,12 +17,6 @@ Within your monitoring.yaml file you can specify the following keys:
 
   * This team key must be already defined in puppet for sensu to recognize it. This is a one time thing, once the team-data exists, your team can use sensu.
 
-    * See the currently defined teams: https://opengrok.yelpcorp.com/xref/sysgit/puppet/hieradata/common.yaml (search for sensu_handlers::teams)
-
-    * Read the docs on the `team-data syntax <https://github.com/Yelp/sensu_handlers/blob/master/README.md#team-syntax>`_
-
-  * If team does not exist, you will need to add it. Instructions on updating the configs is in `Runbook: Puppet <https://docs.google.com/document/d/1T7M0fpw6A8WWo2xzicbxEn_WzRv1IPNfn-wio1KS  E3o/edit#heading=h.k4y6rx1mtq1y>`_
-
 * page: A boolean that indicates if this service's alerts should be email only or escalate to a pager
 
   * Set this to true ONLY if you would want to be woken up in the middle of the night to fix the problem. If you wouldn't, leave page set to false, let it email (or file a ticket or something), and deal with it in the morning

docs/source/soa_configs.rst

@@ -0,0 +1,37 @@
+soa-configs
+===========
+
+soa-configs are the shared configuration storage that PaaSTA uses to hold the
+description and configuration of what services exist and how they should be
+deployed and monitored.
+
+This directory needs to be deployed globally in the same location to every
+server that runs any PaaSTA component.
+
+PaaSTA reads particular config files for each service in the soa-configs
+directory. There is one folder per service. Here is an example tree::
+
+  soa-configs
+  ├── web
+  │   ├── deploy.yaml
+  │   ├── marathon-dev.yaml
+  │   ├── marathon-prod.yaml
+  │   ├── monitoring.yaml
+  │   ├── service.yaml
+  │   └── smartstack.yaml
+  ├── api
+  │   ├── deploy.yaml
+  │   ├── marathon-dev.yaml
+  │   ├── marathon-prod.yaml
+  │   ├── monitoring.yaml
+  │   ├── service.yaml
+  │   └── smartstack.yaml
+  ...
+
+See the `paasta-specific soa-configs documentation <yelpsoa-configs.html>`_ for more information
+about the structure and contents of some example files in soa-configs that PaaSTA uses.
+
+For more information about why we chose this method of config distribution,
+watch `this talk on Yelp's soa-configs and how it is used <https://vimeo.com/141231345>`_.
+
+For reading soa-configs, PaaSTA uses `service_configuration_lib <https://github.com/Yelp/service_configuration_lib>`_.

docs/source/workflow.rst

@@ -16,8 +16,8 @@ Mesos, scheduling crons to run the deployment scripts, etc. See the
 
 Service configuration
 ---------------------
-`CEP 319 <http://y/cep319>`_ discusses how yelpsoa-configs are distributed to
-``/nail/etc/services`` on machines in the cluster.
+``soa-configs`` are used to centrally configure services. See the documentation for
+`soa-configs <soa_configs.html>`_ for more information on what these are.
 
 Contract with services
 ----------------------
@@ -42,10 +42,7 @@ the right state -- cluster X should be running version Y of service Z.
 
 How PaaSTA Runs Docker Containers
 ---------------------------------
-Marathon launches the Docker containers that comprise a PaaSTA service. The
-default configuration is managed by puppet in the `paasta_tools
-module
-<https://opengrok.yelpcorp.com/xref/sysgit/puppet/modules/paasta_tools/manifests/init.pp>`_.
+Marathon launches the Docker containers that comprise a PaaSTA service.
 
 Docker images are run by Mesos's native Docker executor. PaaSTA composes the
 configuration for the running image:
@@ -61,7 +58,7 @@ configuration for the running image:
 
 * ``--env``: Any environment variables specified in the ``env`` section will be here.
 
-  * **WARNING**: A PORT variable is provided to the docker image, but it represents the EXTERNAL port, not the internal one. The internal service MUST listen on 8888, so this PORT variable confuses some service stacks that are listening for this variable. Such services MUST overwrite this environment variable to function. (``PORT=8888 ./uwisgi.py```) We tried to work around this, see `PAASTA-267 <https://jira.yelpcorp.com/browse/PAASTA-267>`_.
+  * **WARNING**: A PORT variable is provided to the docker image, but it represents the EXTERNAL port, not the internal one. The internal service MUST listen on 8888, so this PORT variable confuses some service stacks that are listening for this variable. Such services MUST overwrite this environment variable to function. (``PORT=8888 ./uwisgi.py```)
 
 * ``--publish``: Mesos picks a random port on the host that maps to and exposes
   port 8888 inside the container. This random port is announced to Smartstack

docs/source/yelpsoa_configs.rst

@@ -2,7 +2,7 @@ Preparation: paasta_tools and yelpsoa-configs
 =========================================================
 
 paasta_tools reads configuration about services from several YAML
-files in `yelpsoa-configs <http://y/cep319>`_:
+files in `soa-configs <soa_configs.html>`_:
 
 marathon-[clustername].yaml
 ---------------------------
@@ -267,7 +267,7 @@ smartstack.yaml
 
 The yaml where nerve namespaces are defined and bound to ports.
 
-See `CEP 319 <http://y/cep319>`_
+TODO: Link to nerve/synapse documentation on the format of this file.
 
 monitoring.yaml
 ---------------

general_itests/fake_soa_configs_fsm_wizard/legacy_service/service.yaml

@@ -1,8 +1,8 @@
 ---
 deployed_to: []
-description: Please fill in a one-line description of this service
-external_link: Please add a url to your CEP or SCF here
+description: ""
+external_link: ""
 runs_on:
 - host1
 - host2
-- host3
+- host3

general_itests/fake_soa_configs_fsm_wizard/paasta_service/service.yaml

@@ -1,3 +1,3 @@
 ---
-description: Please fill in a one-line description of this service
-external_link: Please add a url to your CEP or SCF here
+description: ""
+external_link: ""

paasta_tools/generate_services_yaml.py

@@ -13,16 +13,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# CEP 324: Generation of services.yaml file
-
 import sys
 
 import yaml
 from paasta_tools.marathon_tools import get_all_namespaces
 from paasta_tools.utils import atomic_file_write
 
-
-# CEP 337 address for accessing services
 YOCALHOST = '169.254.255.254'
 
 

paasta_tools/paasta_cli/cmds/fsm.py

@@ -59,7 +59,7 @@ def add_subparser(subparsers):
         "--external-link",
         dest="external_link",
         default=None,
-        help="Link to a CEP or SCF of the service. If AUTO will have placeholder text")
+        help="Link to a reference doc for the service. If AUTO will have placeholder text")
     fsm_parser.add_argument(
         "-a",
         "--auto",

paasta_tools/paasta_cli/cmds/info.py

@@ -30,7 +30,10 @@
 NO_DESCRIPTION_MESSAGE = (
     "No 'description' entry in service.yaml. Please a one line sentance that describes this service"
 )
-NO_EXTERNAL_LINK_MESSAGE = "No 'external_link' entry in service.yaml. Please add on that points to your CEP/SCF"
+NO_EXTERNAL_LINK_MESSAGE = (
+    "No 'external_link' entry in service.yaml. "
+    "Please add one that points to a reference doc for your service"
+)
 
 
 def add_subparser(subparsers):
@@ -103,7 +106,7 @@ def get_service_info(service):
     output = []
     output.append('Service Name: %s' % service)
     output.append('Description: %s' % description)
-    output.append('External Link (CEP/SCF): %s' % PaastaColors.cyan(external_link))
+    output.append('External Link: %s' % PaastaColors.cyan(external_link))
     output.append('Monitored By: team %s' % get_team(service=service, overrides={}))
     output.append('Runbook: %s' % PaastaColors.cyan(get_runbook(service=service, overrides={})))
     output.append('Git Repo: %s' % git_url)

paasta_tools/paasta_cli/fsm/questions.py

@@ -52,14 +52,16 @@ def get_description(description, auto):
 def get_external_link(link, auto):
     if link is None:
         if auto:
-            link = "Please add a url to your CEP or SCF here"
+            link = "Please add a link to a reference doc for your service"
         while not link:
-            link = ask('Link to your CEP or SCF?')
+            link = ask('Link to a reference doc?')
     return link
 
 
 def get_smartstack_stanza(yelpsoa_config_root, auto, port):
-    """Produce a smartstack.yaml a la http://y/cep319"""
+    """Produce a basic smartstack.yaml in a `format <yelpsoa_configs.html#smartstack-yaml>`_
+    PaaSTA can use.
+    """
     if port is None:
         suggested_port = suggest_smartstack_proxy_port(yelpsoa_config_root)
         if auto:
@@ -89,8 +91,8 @@ def get_service_stanza(description, external_link, auto):
 
 
 def get_monitoring_stanza(auto, team, legacy_style=False):
-    """Produce a monitoring.yaml a la
-    https://trac.yelpcorp.com/wiki/HowToService/Monitoring/monitoring.yaml
+    """Produce a monitoring.yaml in a `format <yelpsoa_configs.html#monitoring-yaml>`_
+    that PaaSTA can read.
 
     'team' is the critical key and is not calculable so it is required.
 
@@ -159,7 +161,7 @@ def get_clusternames_from_deploy_stanza(deploy_stanza):
 
 def get_marathon_stanza():
     """Produce a ``marathon-*.yaml`` a la
-    http://servicedocs.yelpcorp.com/docs/paasta_tools/yelpsoa_configs.html#marathon-clustername-yaml
+    `the docs <yelpsoa_configs.html#marathon-clustername-yaml>`_
 
     We want to default to The Simplest Thing That Can Possibly Work. This
     allows new services to hit the ground running, but forces developers to