<p>According to <a href="https://kubernetes.io/docs/reference/api-overview/" rel="nofollow noreferrer">https://kubernetes.io/docs/reference/api-overview/</a>, everything at <code>/api/v1</code> is the &quot;legacy&quot; API group. Although the docs don't go into any further detail than that, my natural inference from the use of the word &quot;legacy&quot; is that:</p>
<ul>
<li>I shouldn't use it in new code, and</li>
<li>All its functionality has been reimplemented in other API groups, possibly with a cleaner interface</li>
</ul>
<p>However, in <a href="https://kubernetes.io/docs/tutorials/kubernetes-basics/deploy-interactive/" rel="nofollow noreferrer">Module 2 of the Kubernetes tutorial</a>, I'm instructed to use the legacy API group to access my newly-created pod:</p>
<blockquote>
<p>Now we can make an HTTP request to the application running in that pod:</p>
<pre><code>curl http://localhost:8001/api/v1/proxy/namespaces/default/pods/$POD_NAME/
</code></pre>
</blockquote>
<p>What gives? Does the &quot;legacy&quot; API group actually contain functionality that doesn't exist anywhere else, or is there another, non-legacy way to make requests to my pod that the tutorial just hasn't been updated to reflect?</p>

<p>All newer Kubernetes API objects can be found in <em>named</em> API groups (like, for example, the <code>Deployment</code> object in the <code>apps/v1</code> API group) -- which is also the group that you use in the <code>apiVersion</code> field when declaring new objects.</p>

<p>Older API objects (like the <code>Pod</code> or <code>Service</code> object) are found in the <em>unnamed</em> API group (also called <em>core</em> or <em>legacy</em>). Their <code>apiVersion</code> is just <code>v1</code>, without any name.</p>

<p>In this context, <em>"legacy"</em> does not appear to mean "please do not use it any more". Instead, it seems to mean something like "please do not add any more new objects to this API group". From reading the documentation, it does not look like the "legacy" API group will be deprecated any time soon (after all, it's not like there's any other API that you could use to create a Pod or a Service).</p>

<p>According to the <a href="https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/api-group.md" rel="nofollow noreferrer">respective design proposal</a>, the goal is to...</p>

<blockquote>
  <p>...[break] the monolithic v1 API into modular groups and allowing groups to be enabled/disabled individually. This allows [the Kubernetes developers] to break the monolithic API server to smaller components in the future. [...] For backward compatibility, v1 objects belong to the group with an empty name, so existing v1 config files will remain valid.</p>
</blockquote>
