diff --git a/config.rst b/config.rst index 2a07307..4b4755d 100644 --- a/config.rst +++ b/config.rst @@ -108,27 +108,12 @@ Defines the build flavor; use ``none`` for PHP projects. Size ~~~~ -By default, SymfonyCloud allocates CPU and memory resources to each container -automatically. Some services are optimized for high CPU load, some for high -memory load. By default, SymfonyCloud tries to allocate the largest "fair" size -possible to all services, given the available resources on the plan. That is not -always optimal, however, and you can customize that behavior on any application -container or on any service. +Tweaks the container size. Supported values for the size key are ``AUTO`` (the +default), ``XS``, ``S``, ``M``, ``L``, ``XL``, ``2XL`` and ``4XL``. -Legal values for the size key are ``AUTO`` (the default), ``S``, ``M``, ``L``, -``XL``, ``2XL`` and ``4XL``. - -.. note:: - - Note that in a development environment this value is ignored and always set - to ``S``. It will only take effect in a production deployment (a master - branch with an associated domain). - -.. caution:: - - If the total resources requested by all apps and services is larger than - what the plan size allows then a production deployment will fail with an - error. +Read the documentation about +:doc:`resources allocations ` for more +details about the impact of this parameter. .. _config-disk: diff --git a/cookbooks/index.rst b/cookbooks/index.rst index 33e4487..c8ceec4 100644 --- a/cookbooks/index.rst +++ b/cookbooks/index.rst @@ -24,3 +24,4 @@ Cookbooks robots cloudflare symfony_no_flex + resources_allocation diff --git a/cookbooks/resources_allocation.rst b/cookbooks/resources_allocation.rst new file mode 100644 index 0000000..86fbeeb --- /dev/null +++ b/cookbooks/resources_allocation.rst @@ -0,0 +1,177 @@ +Resources Allocation +==================== + +SymfonyCloud handles resource allocation in a reserved approach, rather than +on-demand. This means that your project (applications plus services) are given a +certain amount of resources and can use as much, or as little, of them as +needed. + +Plan Size +--------- + +Your production plan size determines how much CPU and RAM are available to your +entire production environment. + +.. note:: + + The development plan has no dedicated resources allocated: the main + environment is treated like a + :ref:`development environment ` and container sizes are set + to ``S``. + +You can change your project plan at anytime using the +``symfony project:scale `` command. + +Possible production plan sizes are: + +* Standard +* Medium +* Large +* X-Large +* 2X-Large + +Each plan comes with increasing CPU and memory compared to the previous one. +Please refer to the `SymfonyCloud pricing page`_ to get the official allowance +coming with each plan. + +Container Size +-------------- + +By default, SymfonyCloud allocates CPU and memory resources to each container +automatically. Some services are optimized for high CPU load, some for high +memory load and applications are treated as balanced. By default, SymfonyCloud +tries to allocate the largest "fair" size possible to all containers, given the +available resources on the plan. That is not always optimal, however, and you +can customize that behavior on any application or service container. + +.. caution:: + + If the total resources requested by all apps and services is larger than + what the plan size allows then a production deployment will fail with an + error. + +.. _dev-env-sizing: +.. note:: + + This value is always ignored in development environments and set to ``S``. + It will only take effect in the production environment. This default + development container size can be changed (paid option) if you need to. + Please contact `SymfonyCloud Support`_ for more information. + +Recommendations +~~~~~~~~~~~~~~~ + +For the vast majority of applications, the default fair allocation will be the +best option. In particular it will allow the application to grow as the plan +size increases. If a container is set at a fixed size, however, it will not get +any bigger and the extra resources might go to waste. + +The main use-case where setting size manually is helpful is when setting +particular containers to a fixed size to indicate that it really doesn't need +much CPU or RAM or if its workload is fixed and doesn't need to scale much. +**Static sites**, **background workers**, and other **low-need containers** can +be set that way to allow more resources to go to other applications and services +containers that really need them. For example, keep your main web container on +the auto size and set your Symfony Messenger consumer sending emails to ``XS``. +A :doc:`../services/redis` container - set to ``S`` - holding backend sessions +for an application where traffic is mostly due to stateless API requests is +another plausible scenario. + +Outside of the PHP world, two additional use cases can benefit from setting +these values: + +* Shifting memory allocation from the ``memory_ratio`` to ``base_memory`` (see + the `custom resources allocation`_ section) for applications with a high + baseline need but a low per-request need, such as Java or Go applications. +* For especially memory intensive per-process applications, setting a higher + ``memory_ratio`` (see the `custom resources allocation`_ section) will give + those applications more head room to grow. However, be aware that doing so may + draw memory away from other applications or services that need it. Try to + optimize your application before throwing more resources at it. + +In both cases you will need to do your own profiling to determine optimal values +for your application. + +Service Sizes +~~~~~~~~~~~~~ + +Service sizes are set via the ``size`` property in :doc:`../services/intro`. +Possible values are ``AUTO`` (the default if not set), ``S``, ``M``, ``L``, +``XL``, ``2XL`` and ``4XL``. + +Application Sizes +~~~~~~~~~~~~~~~~~ + +Application (web and workers containers) sizes are set via the ``size`` +properties in :doc:`../config`. Possible values are ``AUTO`` +(the default if not set), ``XS``, ``S``, ``M``, ``L``, ``XL``, ``2XL`` and +``4XL``. + +These sizes have a fixed allocation of CPU associated with them and a default +RAM one: + +==== ==== =========== +Size CPU Default RAM +==== ==== =========== +XS 0.25 128 MB +S 0.5 192 MB +M 1.0 320 MB +L 2.0 576 MB +XL 4.0 1088 MB +2XL 8.0 2112 MB +==== ==== =========== + +.. note:: + + The smaller ``XS`` container size is only available when using custom + resources allocation as describe below in the `custom resources allocation`_ + section. + +Custom Resources Allocation +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + + The default values are appropriate for most reasonably sized scripted + applications (PHP, Python, Node.js, Ruby) and so should rarely be changed. + Please read carefully this section to determine if you actually need to tweak + those settings. + +Application containers have memory allocated based on a default ratio that is +configurable. Two properties can be adjusted: + +.. code-block:: yaml + + resources: + base_memory: 64 #default and minimum + memory_ratio: 256 #defautl, minimum: 128 + +``base_memory`` represents a fixed amount of memory (in megabytes) allocated to +the container. ``memory_ratio`` is an amount of memory allocated per CPU share. +For example: an ``S`` container gets a 0.5 CPU share, with the default +configuration it would get 64 + 0.5 x 256 = 192 MB of RAM. +If the same container gets its size increased to an ``XL``, it would now get +64 + 4 x 256 = 1088 MB of RAM. + +Memory is expressed as two separate values to match different performance +profiles depending on your application needs. + +For instance, a PHP web application needs a relatively low base memory to start +PHP-FPM, but each parallel request consumes some additional memory. It would +benefit from a low ``base_memory`` and a relatively high ``memory_ratio``. That +way, increasing the container size would increase the CPU share allowing more +concurrent requests and its memory allocation naturally scales to match. + +Applications in languages that have a persistent runtime, such as Java or Go, +requires a high baseline memory to boot up but then each parallel request +consumes relatively little memory. They would benefit from a much higher +``base_memory`` value and a lower ``memory_ratio``, so that any container size +has sufficient memory to start the application. + +Background workers can also generally benefit from a higher ``base_memory`` +value and a lower ``memory_ratio`` if they only process one task at a time as +the increase of the CPU share will speed up processing time but will not cause +more tasks to be processed at once so the additional memory is not required. + +.. _SymfonyCloud Support: https://symfony.com/cloud/support +.. _SymfonyCloud pricing page: https://symfony.com/cloud/pricing \ No newline at end of file diff --git a/cookbooks/workers.rst b/cookbooks/workers.rst index e327280..a965049 100644 --- a/cookbooks/workers.rst +++ b/cookbooks/workers.rst @@ -56,6 +56,13 @@ specified by the ``start`` key terminates it will be restarted automatically. possible. Every data sharing needs to be done using :doc:`services `. +.. tip:: + + While worker and application containers share the same ``size`` by default, + they usually benefit from being tweaked separately. Read the documentation + about :doc:`resources allocations ` for more + details about using it. + Accessing a worker container ---------------------------- diff --git a/services/intro.rst b/services/intro.rst index dff1966..d34773a 100644 --- a/services/intro.rst +++ b/services/intro.rst @@ -94,7 +94,12 @@ generate an error if present. Size ~~~~ -This attribute has the same effect as for :ref:`application containers `. +Tweaks the service container size. Supported values for the size key are +``AUTO`` (the default), ``S``, ``M``, ``L``, ``XL``, ``2XL`` and ``4XL``. + +Read the documentation about +:doc:`resources allocations <../cookbooks/resources_allocation>` for more +details about the impact of this parameter. .. tip::