Address more reviews

docs/source/contributing.rst

@@ -37,7 +37,7 @@ Making new versions
 -------------------
 * Make a branch. WRITE TESTS FIRST (TDD)! Add features.
 
-* Submit your branch for review. Include the "PaaSTA" group. Communicate with
+* Submit your branch for review. Include the "paasta" group. Communicate with
   the team to select a single designated Primary Reviewer.
 
 * After ShipIts, merge your branch to master.

docs/source/deploy_groups.rst

@@ -8,7 +8,7 @@ What are deploy groups?
 A deploy group is a group of PaaSTA instances that will be deployed together.
 They provide a way to control how new versions of your service are deployed to production and other environments.
 The ``kubernetes-[clustername].yaml``, ``tron-[clustername].yaml``, and ``adhoc-[clustername].yaml`` files should have a ``deploy_group`` field on each instance.
-The ``paasta mark-for-Deployment`` command (usually run by Jenkins) operates on deploy groups -- it tells PaaSTA that you want a deploy group to run a specific version of your service.
+The ``paasta mark-for-deployment`` command (usually run by Jenkins) operates on deploy groups -- it tells PaaSTA that you want a deploy group to run a specific version of your service.
 In ``deploy.yaml``, you specify the order in which the deploy groups pick up new changes.
 
 As an example, consider a service with the following deploy.yaml:
@@ -41,7 +41,7 @@ Deploy groups in kubernetes/tron yamls and deploy.yaml should match
 
 In almost all cases, you want the list of deploy groups in ``deploy.yaml`` (the ``step`` entries under ``pipeline``, except for the special build/test steps) to match the set of ``deploy_group``s defined in your kubernetes.yaml / tron.yaml / adhoc.yaml.
 If an instance has a ``deploy_group`` that is not defined in deploy.yaml, or your Jenkins pipeline has not run since you added the deploy.yaml entry, PaaSTA won't know what version of your container image this instance should run.
-If a deploy group is specified as a ``step`` in deploy.yaml but is not referenced in any kubernetes/adhoc/tron.yaml, this Deployment step will have no effect.
+If a deploy group is specified as a ``step`` in deploy.yaml but is not referenced in any kubernetes/adhoc/tron.yaml, this deployment step will have no effect.
 
 The ``paasta validate`` command can help you check that the ``deploy_group`` parameter on each of your instances is defined in deploy.yaml.
 

docs/source/installation/getting_started.rst

@@ -33,7 +33,7 @@ are currently not available, so one must build them and install them manually::
   make itest_xenial
   sudo dpkg -i dist/paasta-tools*.deb
 
-This package must be installed anywhere the PaaSTA CLI and on the kube nodes.
+This package must be installed anywhere the PaaSTA CLI is needed and on the kube nodes.
 
 Once installed, ``paasta_tools`` reads global configuration from ``/etc/paasta/``.
 This configuration is in key/value form encoded as JSON. All files in ``/etc/paasta``
@@ -74,7 +74,7 @@ Docker and a Docker Registry
 
 PaaSTA uses `Docker <https://www.docker.com/>`_ to build and distribute code for each service. PaaSTA
 assumes that a single registry is available and that the associated components
-(Docker commands, unix users, etc) have the correct credentials
+(Docker commands, unix users, Kubernetes Nodes, etc) have the correct credentials
 to use it.
 
 The docker registry needs to be defined in a config file in ``/etc/paasta/``.
@@ -116,7 +116,7 @@ SmartStack and Hacheck
 
 `SmartStack <http://nerds.airbnb.com/smartstack-service-discovery-cloud/>`_ is
 a dynamic service discovery system that allows clients to find and route to
-healthy Kubernetes pods for a particular service.
+healthy Kubernetes Pods for a particular service.
 Smartstack consists of two agents: `nerve <https://github.com/airbnb/nerve>`_ and `synapse <https://github.com/airbnb/synapse>`_.
 Nerve is responsible for health-checking services and registering them in ZooKeeper.
 Synapse then reads that data from ZooKeeper and configures an HAProxy instance.

docs/source/isolation.rst

@@ -39,7 +39,6 @@ The master node contains the following components:
   * API Server: Exposes the Kubernetes API. It is the front-end for the Kubernetes control plane.
   * Scheduler: Responsible for distributing workloads across multiple nodes.
   * Controller Manager: Responsible for regulating the state of the cluster.
-  * etcd: Consistent and highly-available key value store used as Kubernetes' backing store for all cluster data.
 
 Worker nodes are the machines that run the workload. Each worker node runs the following components
 to manage the execution and networking of containers:
@@ -62,11 +61,9 @@ criteria into account when selecting a node to have the Pod run on:
 
 The scheduler will then score each node that can host the Pod, based on the criteria above and any custom policies and then select the node
 with the highest score to run the Pod on. If multiple nodes have the same highest score then one of them is chosen randomly. Once a node is selected, the scheduler assigns
-the Pod to the node and the decision is then communicated back to the API server, which in turn notifies the kubelet on the chosen node to start the Pod.
+the Pod to the node and the decision is then communicated back to the API server, which in turn notifies the Kubelet on the chosen node to start the Pod.
 For more information on how the scheduler works, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling/scheduling-framework/).
 
-In PaaSTA, we also run
-
 How PaaSTA services are isolated from each other
 ------------------------------------------------
 
@@ -118,9 +115,8 @@ If the processes in the cgroup reaches the ``memsw.limit_in_bytes`` value ,
 then the kernel will invoke the OOM killer, which in turn will kill off one of
 the processes in the cgroup (often, but not always, this is the biggest
 contributor to the memory usage). If this is the only process running in the
-Docker container, then the container will die. Kubernetes will attempt to reschedule the Pod
-to maintain the desired number of replicas specified in the Deployment. For each PaaSTA instance, a Deployment is created
-which manages the state of the Pods for that instance, ensuring that a specified number of replicas (specified in soa-configs) are running at any given time.
+Docker container, then the container will die. Kubernetes will restart the container
+as the RestartPolicy for the container is set to "Always".
 
 CPUs
 """"
@@ -162,4 +158,4 @@ Disk
 """""
 
 Kubernetes supports disk resource isolation through the use of storage quotas. Disk resource is isolated through the use of
-namespaces - each namespace has a set quota for the total amount of storage that can be requested by the PaaSTA service running in it.
+namespaces - PaaSTA by default apply storage resource limit for the namespace if none is specified (Note: those limits can be overridden in soaconfigs).

docs/source/paasta_development.rst

@@ -18,8 +18,8 @@ PaaSTA playground use cases
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 There are mainly two use cases for PaaSTA playground:
 
-1) :ref:`If the developer wants to debug different components of PaaSTA <debugging-PaaSTA>`
-2) :ref:`If the developer just wants to run PaaSTA to see a change they developed in PaaSTA components <running-PaaSTA>`
+1) :ref:`If the developer wants to debug different components of PaaSTA <debugging-paasta>`
+2) :ref:`If the developer just wants to run PaaSTA to see a change they developed in PaaSTA components <running-paasta>`
 
 Create a Kind Cluster - K8s Cluster
 -----------------------------------
@@ -29,7 +29,7 @@ Before running or debugging PaaSTA playground, you will need to create a Kuberne
 
 To delete the cluster, run ``make k8s_clean``.
 
-.. _debugging-PaaSTA:
+.. _debugging-paasta:
 
 Debugging PaaSTA playground (in VS Code)
 ----------------------------------------
@@ -54,14 +54,14 @@ and select the configuration you want to run the debugger with, then press on ``
 
 For more information on how to run the VS Code debugger, please refer to `VS Code Documentation <https://code.visualstudio.com/docs/editor/debugging>`_
 
-.. _debugging-PaaSTA-playground:
+.. _debugging-paasta-playground:
 
 Debugging PaaSTA playground components (in VS Code)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Steps below outline running PaaSTA playground components with a debugger attached:
 
-1. Run ``make generate_Deployments_for_service`` to run the Make targets that generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and the ``Deployments.json`` file.
+1. Run ``make generate_deployments_for_service`` to run the Make targets that generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and the ``deployments.json`` file.
 2. [This step can be ran one time] From the ``Run and Debug`` tab in VS Code, press on ``Run setup k8s job in playground`` to deploy ``compute-infra-test-service`` service in the cluster, if it's not deployed.
 
    .. sourcecode:: shell
@@ -79,8 +79,8 @@ Steps below outline running PaaSTA playground components with a debugger attache
       compute-infra-test-service-autoscaling-6fdf96b485-pb6mm   1/1     Running   0          25s
       compute-infra-test-service-autoscaling-6fdf96b485-v8shw   1/1     Running   0          25s
 
-3. From the ``Run and Debug`` tab in VS Code, press on ``PaaSTA API playground`` to run PaaSTA API
-4. Wait until workers are booted in API output then from the ``Run and Debug`` tab in VS Code, press on ``PaaSTA status playground`` to run the PaaSTA ClI client to connect to the API.
+3. From the ``Run and Debug`` tab in VS Code, press on ``paasta API playground`` to run PaaSTA API
+4. Wait until workers are booted in API output then from the ``Run and Debug`` tab in VS Code, press on ``paasta status playground`` to run the PaaSTA ClI client to connect to the API.
 
 Observe paaSTA API logs to check for connection from the client.
 
@@ -96,7 +96,7 @@ Expected output from client:
               ReplicaSet Name                                    Ready / Desired  Created at what localtime         Service git SHA                           Config hash
               compute-infra-test-service-autoscaling-6fdf96b485  10/10            2022-12-14T08:19 (2 minutes ago)  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  configxxxx
 
-.. _running-PaaSTA:
+.. _running-paasta:
 
 Running PaaSTA playground
 -------------------------
@@ -112,6 +112,6 @@ If you didn't run ``setup_kubernetes_job`` to deploy ``compute-infra-test-servic
 
 2. Using make targets
 
-   1. Run ``make setup_kubernetes_job`` to run the Make target that generates the  ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``Deployments.json`` file and deploys workloads to the cluster.
+   1. Run ``make setup_kubernetes_job`` to run the Make target that generates the  ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``deployments.json`` file and deploys workloads to the cluster.
    2. Run ``make playground-api`` to run the Make target that runs PaaSTA API.
-   3. Wait until workers are booted in API output then from the ``Run and Debug`` tab in VS Code, press on ``PaaSTA status playground`` to run the PaaSTA ClI client to connect to the API.
+   3. Wait until workers are booted in API output then from the ``Run and Debug`` tab in VS Code, press on ``paasta status playground`` to run the PaaSTA ClI client to connect to the API.

docs/source/style_guide.rst

@@ -23,12 +23,12 @@ Examples
 ^^^^^^^^
 
 Good:
- * paasta mark-for-Deployment => Goes to stdout. (But also scribe)
+ * paasta mark-for-deployment => Goes to stdout. (But also scribe)
 Bad:
- * paasta mark-for-Deployment => Going to scribe only, which is surprising.
+ * paasta mark-for-deployment => Going to scribe only, which is surprising.
 
 Good:
- * PaaSTA itest => Sends event-level detail to stdout
+ * paasta itest => Sends event-level detail to stdout
 
 Example::
 
@@ -40,7 +40,7 @@ Example::
   etc"
 
 Bad:
- * PaaSTA itest => Sends all output to scribe, no output to stdout. Jenkins console output is empty and surprises users.
+ * paasta itest => Sends all output to scribe, no output to stdout. Jenkins console output is empty and surprises users.
 
  * Scribe: Tools that contribute to the overall flow of a service pipeline should log to scribe with their given component. Only log lines that are specific to a service should be sent here. Logging to scribe should be selective and precise as to not overwhelm the event stream.
 
@@ -52,9 +52,9 @@ Bad:
  * setup_kubernetes_job | stdint2scribe (no selective filtering, raw stdout dump)
 
 Good:
- * PaaSTA itest => Sends summary of pass or fail to scribe event log. Sends full output of the run to the scribe debug log
+ * paasta itest => Sends summary of pass or fail to scribe event log. Sends full output of the run to the scribe debug log
 Bad:
- * PaaSTA itest => Sends every line of the ``make itest`` output to ``event`` level, drowning out other key event lines.
+ * paasta itest => Sends every line of the ``make itest`` output to ``event`` level, drowning out other key event lines.
 
  * Syslog: Non-interactive system processes that do not send data to developers can use syslog, but via stdout => logger. Do not send to syslog directly.
 
@@ -87,7 +87,7 @@ Event Level General Guidelines:
 
 Good examples of things that would be in the ``event`` level log stream:
 
-* ``40e74f marked for Deployment in cluster.main``
+* ``40e74f marked for deployment in cluster.main``
 * ``upthendown bounce initiated on instance main``
 * ``itest Passed for 9e2990.``
 * ``itest Failed for 9e2990. More info: http://....``

docs/source/system_configs.rst

@@ -17,7 +17,7 @@ are overlapping keys in different files the last file will win.
 If a file has permissions that prevent us from reading it, then that file will be ignored.
 This is useful for credentials that only some users or scripts need access to.
 
-See `load_system_PaaSTA_config <generated/PaaSTA_tools.utils.html#PaaSTA_tools.utils.load_system_PaaSTA_config>`_ for
+See `load_system_paasta_config <generated/paasta_tools.utils.html#paasta_tools.utils.load_system_paasta_config>`_ for
 more details on how system configs are loaded.
 
 

docs/source/workflow.rst

@@ -33,7 +33,7 @@ Adhoc tasks are often required to support one-time tasks, like a database
 migration.  Sometimes they are also useful for exploratory purposes, or even
 sometimes for end-to-end tests. PaaSTA supports this use case through ``paasta
 local-run``, which supports building images locally, as well as using the same
-image as a "live" Deployment.
+image as a "live" deployment.
 
 See the `adhoc instances <adhoc_instances.html>`_ doc for more information on
 running adhoc instances using ``paasta local-run``.
@@ -52,14 +52,14 @@ The `Paasta Contract <about/contract.html>`_ describes the
 responsibilities of services that wish to work with PaaSTA.
 
 paasta_tools contains the implementation of several of these rules.
-For example, `generate_Deployments_for_service <generate_Deployments_for_service.html>`_ is
+For example, `generate_deployments_for_service <generate_deployments_for_service.html>`_ is
 the piece that checks each service's git repo for the specially-named branch
 that tells PaaSTA which versions of the service should go to which clusters.
 
 Deployment
 ----------
-A yelpsoa-configs master runs `generate_Deployments_for_service <generated/paasta_tools.generate_Deployments_for_service.html>`_
-frequently. The generated ``Deployments.json`` appears in ``/nail/etc/services/service_name`` throughout the cluster.
+A yelpsoa-configs master runs `generate_deployments_for_service <generated/paasta_tools.generate_deployments_for_service.html>`_
+frequently. The generated ``deployments.json`` appears in ``/nail/etc/services/service_name`` throughout the cluster.
 
 How PaaSTA Runs Docker Containers
 ---------------------------------
@@ -126,14 +126,15 @@ monitoring checks for free:
 
 * **check_kubernetes_services_replication**:
   runs periodically and sends an alert if fewer than 50% of the requested
-  instances are deployed on a cluster. it will look in Smartstack to count the available instances
-  against the expected amount of instances that should've been deployed via Kubernetes.
+  instances are deployed on a cluster. If the service is registered in Smartstack
+  it will look in Smartstack to count the available instances. Otherwise it
+  counts the number of healthy Pods in Kubernetes.
 
 
 The PaaSTA command line
 ------------------------
 
-The PaaSTA command line interface, ``PaaSTA``, gives users of PaaSTA the
+The PaaSTA command line interface, ``paasta``, gives users of PaaSTA the
 ability to inspect the state of services, as well as stop and start existing
 services. See the man pages for a description and detail of options for any
 individual PaaSTA command.  Some of the most frequently used commands are