Added documentation to readthedocs for paasta playground - PAASTA-17768 #3478
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
EmanElsaban
changed the title
nemacysts
reviewed
Oct 13, 2022
docs/source/PaaSTA_Development.rst
Outdated
| ================== | ||
|
|
||
|
|
||
| What is PaaSTA playground |
There was a problem hiding this comment.
super-nit:
Suggested change
| What is PaaSTA playground | |
| What is the PaaSTA playground? |
docs/source/PaaSTA_Development.rst
Outdated
| What is PaaSTA playground | ||
| ------------------------- | ||
|
|
||
| PaaSTA playground allows the developer to run and debug paasta locally on an ephemeral Kubernetes cluster. Currently, it includes the following components: |
There was a problem hiding this comment.
super-nit:
Suggested change
| PaaSTA playground allows the developer to run and debug paasta locally on an ephemeral Kubernetes cluster. Currently, it includes the following components: | |
| PaaSTA playground allows the developer to run and debug PaaSTA locally on an ephemeral Kubernetes cluster. Currently, it includes the following components: |
docs/source/PaaSTA_Development.rst
Outdated
Comment on lines
10
to
11
| generating ``etc_paasta_playground`` and ``soa_config_playground`` directories, setup_kubernetes_job (deploy compute-infra-test-service), | ||
| PaaSTA API, and PaaSTA CLI client. |
There was a problem hiding this comment.
hmm, might be good to expand on some of these pieces in the future (i.e., so that we can point a new hire to this and not need to explain what things like etc_paasta_playground are)
e.g.,
* generating ``etc_paasta_playground`` (stores system-level PaaSTA configuration)
* generating ``soa_config_playground`` (stores what services PaaSTA should manage)
* running setup_kubernetes_job (the tool we use to deploy services on Kubernetes)
* starting the PaaSTA API (the backend that the PaaSTA CLI talks to)
* configuring the PaaSTA CLI (the interface to interacting with PaaSTA)
but this can be done in another PR unless we really wanna do this now
docs/source/PaaSTA_Development.rst
Outdated
| Create a Kind Cluster - K8s Cluster | ||
| ----------------------------------- | ||
|
|
||
| Before running or debugging PaaSTA playground, you will need to create a kubernetes cluster - Kind. You can do so by running the make target |
There was a problem hiding this comment.
super-nit:
Suggested change
| Before running or debugging PaaSTA playground, you will need to create a kubernetes cluster - Kind. You can do so by running the make target | |
| Before running or debugging PaaSTA playground, you will need to create a Kubernetes cluster using ``kind``. You can do so by running the Make target |
docs/source/PaaSTA_Development.rst
Outdated
| ----------------------------------- | ||
|
|
||
| Before running or debugging PaaSTA playground, you will need to create a kubernetes cluster - Kind. You can do so by running the make target | ||
| ``make create_cluster`` from ``paasta/k8s_itests`` directory. |
There was a problem hiding this comment.
super-nit:
Suggested change
| ``make create_cluster`` from ``paasta/k8s_itests`` directory. | |
| ``make create_cluster`` from the ``paasta/k8s_itests`` directory. |
docs/source/PaaSTA_Development.rst
Outdated
| In order to run the debugger with any of the configurations in ``launch.json``, you can go to ``Run and Debug`` tab in VS Code | ||
|
|
||
| .. image:: run_and_debug_tab.png | ||
| :width: 700px |
There was a problem hiding this comment.
nit: could we make these images 700px wide so that we don't need to resize them in the browser? should also make the file size smaller if we shrink the picture size :)
There was a problem hiding this comment.
ohh sorry I'm confused. The images width is already set to 700px, do you mean to decrease this value?
There was a problem hiding this comment.
oh sorry, i meant: we should make the raw image be exactly the size that we want to display it as rather than having browsers/rst resize the image for us (i.e., edit the image to be exactly 700px wide)
docs/source/PaaSTA_Development.rst
Outdated
|
|
||
| .. _running-debugger: | ||
|
|
||
| Running debugger (in VS Code) |
There was a problem hiding this comment.
super-nit:
Suggested change
| Running debugger (in VS Code) | |
| Running the debugger (in VS Code) |
docs/source/PaaSTA_Development.rst
Outdated
|
|
||
| Steps below outline running PaaSTA playground components with a debugger attached: | ||
|
|
||
| 1. Run the make target ``generate_etc_paasta_playground`` to generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``deployments.json`` file. |
There was a problem hiding this comment.
super-nit:
Suggested change
| 1. Run the make target ``generate_etc_paasta_playground`` to generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``deployments.json`` file. | |
| 1. Run t ``generate_etc_paasta_playground`` to run the Make target that generates the ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``deployments.json`` file. |
| 1. Run the make target ``generate_etc_paasta_playground`` to generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``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. | ||
|
|
||
| Note: we're expecting to see the service in ``pending status`` as zookeeper component doesn't exist yet in paaSTA playground: |
There was a problem hiding this comment.
do we need zk running to start pods in kind? afaik, the only thing inside our infra that uses zk in paasta is some service mesh stuff
There was a problem hiding this comment.
yes, I think so. When I run setup_kubernetes_job.py it gives me this at the end of the output:
INFO:__main__:Creating compute-infra-test-service-autoscaling-0ae13cf29612fb38bbf1ad40652cdf93abfe41df-config1e4fda94 because it does not exist yet.
INFO:root:creating poddisruptionbudget compute-infra-test-service-autoscaling
ERROR:__main__:Error while processing: compute-infra-test-service-autoscaling-0ae13cf29612fb38bbf1ad40652cdf93abfe41df-config1e4fda94
Traceback (most recent call last):
File "/nail/home/emanelsabban/pg/paasta/paasta_tools/utils.py", line 2080, in get_zk_hosts
hosts = self.config_dict["zookeeper"]
KeyError: 'zookeeper'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/nail/home/emanelsabban/pg/paasta/paasta_tools/setup_kubernetes_job.py", line 176, in setup_kube_deployments
app.create(kube_client)
File "/nail/home/emanelsabban/pg/paasta/paasta_tools/kubernetes/application/controller_wrappers.py", line 231, in create
self.sync_horizontal_pod_autoscaler(kube_client)
File "/nail/home/emanelsabban/pg/paasta/paasta_tools/kubernetes/application/controller_wrappers.py", line 308, in sync_horizontal_pod_autoscaler
should_have_hpa = desired_hpa_spec and not autoscaling_is_paused()
File "/nail/home/emanelsabban/pg/paasta/paasta_tools/autoscaling/autoscaling_service_lib.py", line 839, in autoscaling_is_paused
with ZookeeperPool() as zk:
File "/nail/home/emanelsabban/pg/paasta/paasta_tools/utils.py", line 3820, in __enter__
hosts=load_system_paasta_config().get_zk_hosts(), read_only=True
File "/nail/home/emanelsabban/pg/paasta/paasta_tools/utils.py", line 2084, in get_zk_hosts
% self.directory
paasta_tools.utils.PaastaNotConfiguredError: Could not find zookeeper connection string in configuration directory: ./etc_paasta_playground/
It looks for a zookeeper connection string
There was a problem hiding this comment.
ah interesting - forgot that we had this!
might be worth making a ticket for future-us to make this fail more smoothly (probably default to autoscaling enabled if we can't talk to zk?) since it doesn't seem ideal to have pending pods when there's no zk to talk to (even if this is only likely to happen when running in a playground env)
There was a problem hiding this comment.
sounds good, will create a ticket :)
docs/source/PaaSTA_Development.rst
Outdated
Comment on lines
104
to
107
| 2. Using make targets | ||
|
|
||
| 1. Run the make target ``make generate_paasta_playground`` to generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``deployments.json`` file. | ||
| 2. Run make target ``make playground-api`` to run the PaaSTA API. |
There was a problem hiding this comment.
super-nit:
Suggested change
| 2. Using make targets | |
| 1. Run the make target ``make generate_paasta_playground`` to generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``deployments.json`` file. | |
| 2. Run make target ``make playground-api`` to run the PaaSTA API. | |
| 2. Using >ake targets | |
| 1. Run ``make generate_paasta_playground`` to run the Make target that generate the ``etc_paasta_playground`` and ``soa_config_playground`` directories and ``deployments.json`` file. | |
| 2. Run ``make playground-api`` to run the Make target that runs the PaaSTA API. |
EmanElsaban
force-pushed
the
u/emanelsabban/paasta_playground_documentation
branch
from
c25cf00 to
8c44e15
Compare
nemacysts
approved these changes
Oct 18, 2022
EmanElsaban
force-pushed
the
u/emanelsabban/paasta_playground_documentation
branch
from
f1397ff to
0079022
Compare
nemacysts
approved these changes
Oct 24, 2022
docs/source/PaaSTA_Development.rst
Outdated
| 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>` |
There was a problem hiding this comment.
Suggested change
| 2) :ref:`If the developer just wants to run paasta to see a change they developed in PaaSTA components <running-paasta>` | |
| 2) :ref:`If the developer just wants to run PaaSTA to see a change they developed in PaaSTA components <running-paasta>` |
There was a problem hiding this comment.
thanks will fix it now
nemacysts
approved these changes
Oct 24, 2022
EmanElsaban
force-pushed
the
u/emanelsabban/paasta_playground_documentation
branch
from
9401a91 to
08f5dc3
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
In this PR, I added documentation related to debugging and running paasta playground.
Testing
I tried viewing the RST document using a VS Code RST extension to ensure there are no syntax mistakes.