https://www.okteto.com/docs/assets/js/17c2ebb6.957d1efc.js

1/*! For license information please see 17c2ebb6.957d1efc.js.LICENSE.txt */
2(self.webpackChunk_okteto_website_docs=self.webpackChunk_okteto_website_docs||[]).push([[7733],{12807:(e,i,t)=>{"use strict";t.d(i,{A:()=>n});const n=t.p+"assets/images/smart-builds-cindy-c56a5e641cd584409eecaf2df2f27da8.png"},20998:(e,i,t)=>{"use strict";t.d(i,{A:()=>n});const n=t.p+"assets/images/smart-builds-david-5362c0caee933d6509ebfd343fd12aec.png"},22475:(e,i,t)=>{"use strict";t.d(i,{A:()=>c});t(96540);var n=t(46942),s=t.n(n);const a="Image_BJUz",o="ImageCenter_fE7C",r="ImageBorderless_Quyg";var l=t(74848);const c=function(e){let{src:i,loading:t}=e;if(!i.match(/^((http|https):\/\/|\/)/)&&"undefined"!=typeof window){i=("/"+window.location.pathname.replace(/index\.[a-z]+$/,"").split("/").filter(Boolean).slice(0,-1).join("/")+"/"+i).replace(/\/{2,}/,"/")}const n=Object.assign({},e,{src:i,loading:t||"lazy",center:void 0,borderless:void 0});return(0,l.jsx)("img",Object.assign({},n,{className:s()(a,{[o]:e.center,[r]:e.borderless})}))}},28453:(e,i,t)=>{"use strict";t.d(i,{R:()=>o,x:()=>r});var n=t(96540);const s={},a=n.createContext(s);function o(e){const i=n.useContext(a);return n.useMemo(function(){return"function"==typeof e?e(i):{...i,...e}},[i,e])}function r(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:o(e.components),n.createElement(a.Provider,{value:i},e.children)}},33380:(e,i,t)=>{"use strict";t.d(i,{A:()=>n});const n=t.p+"assets/images/buildkit-f5339b2c69537cf1cc499da268346fc4.png"},46942:(e,i)=>{var t;!function(){"use strict";var n={}.hasOwnProperty;function s(){for(var e="",i=0;i<arguments.length;i++){var t=arguments[i];t&&(e=o(e,a(t)))}return e}function a(e){if("string"==typeof e||"number"==typeof e)return e;if("object"!=typeof e)return"";if(Array.isArray(e))return s.apply(null,e);if(e.toString!==Object.prototype.toString&&!e.toString.toString().includes("[native code]"))return e.toString();var i="";for(var t in e)n.call(e,t)&&e[t]&&(i=o(i,t));return i}function o(e,i){return i?e?e+" "+i:e+i:e}e.exports?(s.default=s,e.exports=s):void 0===(t=function(){return s}.apply(i,[]))||(e.exports=t)}()},64010:(e,i,t)=>{"use strict";t.r(i),t.d(i,{assets:()=>c,contentTitle:()=>l,default:()=>u,frontMatter:()=>r,metadata:()=>n,toc:()=>d});const n=JSON.parse('{"id":"core/build-service","title":"Okteto Build service","description":"The Okteto Build service allows you to build your container images remotely","source":"@site/versioned_docs/version-1.39/core/build-service.mdx","sourceDirName":"core","slug":"/core/build-service","permalink":"/docs/1.39/core/build-service","draft":false,"unlisted":false,"editUrl":"https://github.com/okteto/docs/edit/main/versioned_docs/version-1.39/core/build-service.mdx","tags":[],"version":"1.39","frontMatter":{"title":"Okteto Build service","description":"The Okteto Build service allows you to build your container images remotely","sidebar_label":"Okteto Build service","id":"build-service"},"sidebar":"docs","previous":{"title":"Namespaces","permalink":"/docs/1.39/core/namespaces"},"next":{"title":"Okteto Insights Dashboards","permalink":"/docs/1.39/core/okteto-insights-dashboards"}}');var s=t(74848),a=t(28453),o=t(22475);const r={title:"Okteto Build service",description:"The Okteto Build service allows you to build your container images remotely",sidebar_label:"Okteto Build service",id:"build-service"},l=void 0,c={},d=[{value:"How to build your images",id:"how-to-build-your-images",level:2},{value:"Dockerfile Compatibility",id:"dockerfile-compatibility",level:2},{value:"Mount Cache ID Management",id:"mount-cache-id-management",level:3},{value:"Sharing Caches Between Repositories",id:"sharing-caches-between-repositories",level:3},{value:"Smart Builds",id:"smart-builds",level:2},{value:"Prerequisite: Git environment required",id:"prerequisite-git-environment-required",level:3},{value:"Limitations with explicit image tags",id:"limitations-with-explicit-image-tags",level:3},{value:"Skipping Smart Builds behavior",id:"skipping-smart-builds-behavior",level:2},{value:"Advanced timeouts configuration",id:"advanced-timeouts-configuration",level:2}];function h(e){const i={a:"a",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsxs)(i.p,{children:["Every time you build your images with Okteto, your build is executed in a remote ",(0,s.jsx)(i.a,{href:"https://github.com/moby/buildkit",children:"BuildKit"})," server running in your cluster, deployed automatically by Okteto.\nThe image is also pushed to the ",(0,s.jsx)(i.a,{href:"/docs/1.39/core/container-registry",children:"Okteto Registry"}),".\nThe following image illustrates this process:"]}),"\n",(0,s.jsx)("p",{align:"center",children:(0,s.jsx)(o.A,{src:t(33380).A,alt:"Buildkit architecture",width:"850"})}),"\n",(0,s.jsx)(i.p,{children:"The Okteto Build service addresses common issues that often slow down image builds such as limited local resources, inefficient emulation, and the lack of reusing images and cache layers already computed by other team members."}),"\n",(0,s.jsx)(i.h2,{id:"how-to-build-your-images",children:"How to build your images"}),"\n",(0,s.jsxs)(i.p,{children:["The Okteto CLI is automatically configured to interact with the Okteto Build service (follow our docs to ",(0,s.jsx)(i.a,{href:"/docs/1.39/get-started/install-okteto-cli",children:"install and configure the Okteto CLI"}),").\nFor example, if your have the following Okteto Manifest:"]}

2),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-yaml",metastring:'title="okteto.yaml"',children:"build:\n  api:\n    context: api\n    dockerfile: Dockerfile\n    args:\n      GO_VERSION: 1.20\n"})}),"\n",(0,s.jsxs)(i.p,{children:["The command ",(0,s.jsx)(i.code,{children:"okteto build"})," will build and push the ",(0,s.jsx)(i.strong,{children:"api"})," image to the Okteto Registry using the Okteto Build service:"]}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:"okteto build\n"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:" i  Using cindy @ okteto.example.com as context\n i  Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443...\n ...\n \u2713  Image 'registry.okteto.example.com/cindy/api:okteto' successfully pushed\n"})}),"\n",(0,s.jsxs)(i.p,{children:["Read our documentation about the ",(0,s.jsxs)(i.a,{href:"/docs/1.39/reference/okteto-manifest#build-object-optional",children:[(0,s.jsx)(i.code,{children:"build"})," section"]})," and the ",(0,s.jsxs)(i.a,{href:"/docs/1.39/reference/okteto-cli#build",children:[(0,s.jsx)(i.code,{children:"okteto build"})," command"]})," for more information."]}),"\n",(0,s.jsx)(i.h2,{id:"dockerfile-compatibility",children:"Dockerfile Compatibility"}),"\n",(0,s.jsx)(i.p,{children:"Okteto Build is compatible with Dockerfile syntax. We leverage BuildKit's full capabilities, so any valid Dockerfile will work seamlessly with the Okteto Build service."}),"\n",(0,s.jsx)(i.h3,{id:"mount-cache-id-management",children:"Mount Cache ID Management"}),"\n",(0,s.jsxs)(i.p,{children:["The only difference in Okteto Build compared to standard Docker behavior is how we manage the default ID for ",(0,s.jsx)(i.a,{href:"https://docs.docker.com/build/cache/optimize/#use-your-package-manager-wisely",children:"mount caches"}),"."]}),"\n",(0,s.jsx)(i.p,{children:(0,s.jsx)(i.strong,{children:"Docker's default behavior:"})}),"\n",(0,s.jsxs)(i.ul,{children:["\n",(0,s.jsx)(i.li,{children:"The default cache ID is based solely on the target path"}),"\n",(0,s.jsxs)(i.li,{children:["Example: ",(0,s.jsx)(i.code,{children:"RUN --mount=type=cache,target=/go/pkg/mod"})," uses ",(0,s.jsx)(i.code,{children:"/go/pkg/mod"})," as the cache ID"]}),"\n"]}),"\n",(0,s.jsx)(i.p,{children:(0,s.jsx)(i.strong,{children:"Okteto's default behavior:"})}),"\n",(0,s.jsxs)(i.ul,{children:["\n",(0,s.jsxs)(i.li,{children:["The default cache ID is based on the target path ",(0,s.jsx)(i.strong,{children:"and"})," the current git repository name"]}),"\n",(0,s.jsxs)(i.li,{children:["Example: For repository ",(0,s.jsx)(i.code,{children:"myapp"}),", the same mount would use ",(0,s.jsx)(i.code,{children:"myapp-/go/pkg/mod"})," as the cache ID"]}),"\n"]}),"\n",(0,s.jsx)(i.p,{children:"This difference ensures that different repositories using the same target folder don't accidentally share the same cache, which could lead to unexpected behavior or conflicts."}),"\n",(0,s.jsx)(i.h3,{id:"sharing-caches-between-repositories",children:"Sharing Caches Between Repositories"}),"\n",(0,s.jsx)(i.p,{children:"If you want to explicitly share caches between different repositories, you can manually set the cache ID:"}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-dockerfile",children:"# Explicitly set a cache ID to share between repositories\nRUN --mount=type=cache,target=/go/pkg/mod,id=shared-go-cache \\\n    go mod download\n\n# Or share npm cache across multiple projects\nRUN --mount=type=cache,target=/root/.npm,id=shared-npm-cache \\\n    npm ci\n"})}),"\n",(0,s.jsxs)(i.p,{children:["For more information about mount caches and cache optimization, see the ",(0,s.jsx)(i.a,{href:"https://docs.docker.com/build/cache/optimize/#use-your-package-manager-wisely",children:"official Docker documentation on build cache"}),"."]}),"\n",(0,s.jsx)(i.h2,{id:"smart-builds",children:"Smart Builds"}),"\n",(0,s.jsxs)(i.p,{children:["Buildkit comes with a local cache to reuse cache layers between image builds.\nYou can configure the ",(0,s.jsx)(i.a,{href:"/docs/1.39/self-hosted/helm-configuration#buildkit",children:"Buildkit cache size and storage class"})," when installing Okteto to optimize the BuildKit cache behavior."]}),"\n",(0,s.jsx)(i.p,{children:"But the Buildkit cache has its own limitations. Even if every Dockerfile instruction is cached, you might wait 1 or 2 minutes until your build context is sent to Buildkit, Buildkit pulls your base image, detects that each Dockerfile instruction can be cached, and push the final image again to the Okteto Registry."}),"\n",(0,s.jsxs)(i.p,{children:["Smart Builds is an Okteto's feature designed to solve this problem.\nFor each image you build, Okteto computes a ",(0,s.jsx)(i.co

2de,{children:"hash"})," based on the build context and the rest of build parameters.\nOkteto uses this hash to detect if the image has been already built by any other developer. If the image was already built, the build is skipped and the previous image is reused almost immediately."]}),"\n",(0,s.jsxs)(i.p,{children:["Smart Builds are implemented by pushing a tag with the value of the ",(0,s.jsx)(i.code,{children:"hash"})," to the namespace ",(0,s.jsx)(i.code,{children:"okteto"})," in the Okteto Registry.\nFor example, if you build the following image:"]}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-yaml",metastring:'title="okteto.yaml"',children:"build:\n  api:\n    context: api\n    dockerfile: Dockerfile\n    args:\n      GO_VERSION: 1.20\n"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:"okteto build\n"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:" i  Using cindy @ okteto.example.com as context\n i  Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443...\n ...\n => pushing manifest for registry.okteto.example.com/okteto/api:09f8e\n \u2713  Image 'registry.okteto.example.com/cindy/api:okteto' successfully pushed\n"})}),"\n",(0,s.jsxs)(i.p,{children:["As you can see in the following image, the image is pushed to ",(0,s.jsx)(i.code,{children:"okteto/api:09f8e"}),":"]}),"\n",(0,s.jsx)("p",{align:"center",children:(0,s.jsx)(o.A,{src:t(98710).A,alt:"Smart builds",width:"850"})}),"\n",(0,s.jsxs)(i.p,{children:["Also, ",(0,s.jsx)(i.code,{children:"cindy/api:okteto"})," is re-tagged to ",(0,s.jsx)(i.code,{children:"okteto/api:09f8e"})," to remember the last build performed in a given namespace.\nThe following image illustrates this process:"]}),"\n",(0,s.jsx)("p",{align:"center",children:(0,s.jsx)(o.A,{src:t(12807).A,alt:"Smart builds",width:"850"})}),"\n",(0,s.jsxs)(i.p,{children:["If another user, ",(0,s.jsx)(i.strong,{children:"David"}),", builds the same image with the same build context and parameters, the same hash ",(0,s.jsx)(i.code,{children:"09f8e"})," is computed."]}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:"okteto build\n"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:' i  Using david @ okteto.example.com as context\n i  Okteto Smart Builds is skipping build of "api" because it\'s already built\n'})}),"\n",(0,s.jsxs)(i.p,{children:["Smart builds detects that the tag ",(0,s.jsx)(i.code,{children:"okteto/api:09f8e"})," already exists and skips the build.\nInstead, the image ",(0,s.jsx)(i.code,{children:"david/api:okteto"})," is re-tagged to ",(0,s.jsx)(i.code,{children:"okteto/api:09f8e"})," to remember the last build performed in the David's namespace:"]}),"\n",(0,s.jsx)("p",{align:"center",children:(0,s.jsx)(o.A,{src:t(20998).A,alt:"Smart builds",width:"850"})}),"\n",(0,s.jsx)(i.h3,{id:"prerequisite-git-environment-required",children:"Prerequisite: Git environment required"}),"\n",(0,s.jsx)(i.p,{children:"Smart Builds needs access to a git repository to compute the content hash correctly. It uses more than just the branch and commit; it also inspects diffs, untracked files, and folder content to determine whether a build can be skipped."}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsx)(i.strong,{children:"Environment variables are not enough:"})," setting ",(0,s.jsx)(i.code,{children:"OKTETO_GIT_BRANCH"})," or ",(0,s.jsx)(i.code,{children:"OKTETO_GIT_COMMIT"})," manually will not enable Smart Builds without an actual git repository present."]}),"\n",(0,s.jsxs)(i.p,{children:[(0,s.jsxs)(i.strong,{children:["Using Compose or commands in ",(0,s.jsx)(i.code,{children:"deploy"}),":"]})," when your manifest runs Okteto CLI commands that trigger image builds (for example, under ",(0,s.jsx)(i.code,{children:"deploy: commands:"})," running ",(0,s.jsx)(i.code,{children:"okteto deploy -f compose.yml"}),"), ensure the ",(0,s.jsx)(i.code,{children:".git"})," directory is not excluded by ",(0,s.jsx)(i.code,{children:".oktetoignore"}),". Otherwise, Smart Builds cannot access git metadata and will fall back to a full build."]}),"\n",(0,s.jsx)(i.h3,{id:"limitations-with-explicit-image-tags",children:"Limitations with explicit image tags"}),"\n",(0,s.jsxs)(i.p,{children:["Smart Builds are automatically disabled 

2when you explicitly define the ",(0,s.jsx)(i.code,{children:"image"})," field with a custom tag in your build configuration. Smart Builds work by generating a SHA based on your git repository status and using that SHA as the image tag. When you specify your own image tag, Smart Builds cannot determine if the build should be skipped."]}),"\n",(0,s.jsx)(i.p,{children:(0,s.jsx)(i.strong,{children:"Examples that will NOT use Smart Builds:"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-yaml",children:'build:\n  api:\n    # Explicit image tag disables Smart Builds\n    image: "registry.okteto.example.com/${OKTETO_NAMESPACE}/movies-api:custom"\n    context: api\n    dockerfile: Dockerfile\n'})}),"\n",(0,s.jsx)(i.p,{children:(0,s.jsx)(i.strong,{children:"Examples that WILL use Smart Builds:"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-yaml",children:"build:\n  api:\n    # No image field specified - Smart Builds enabled\n    context: api\n    dockerfile: Dockerfile\n    args:\n      GO_VERSION: 1.20\n"})}),"\n",(0,s.jsx)(i.h2,{id:"skipping-smart-builds-behavior",children:"Skipping Smart Builds behavior"}),"\n",(0,s.jsx)(i.p,{children:"You can force the build of your images and skip the Smart Build optimization by running the following command:"}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:"okteto build --no-cache\n"})}),"\n",(0,s.jsx)(i.pre,{children:(0,s.jsx)(i.code,{className:"language-bash",children:" i  Using cindy @ okteto.example.com as context\n i  Building 'api/Dockerfile' in tcp://buildkit.okteto.example.com:443...\n ...\n => pushing manifest for registry.okteto.example.com/okteto/api:09f8e\n \u2713  Image 'registry.okteto.example.com/cindy/api:okteto' successfully pushed\n"})}),"\n",(0,s.jsxs)(i.p,{children:["The ",(0,s.jsx)(i.code,{children:"--no-cache"})," flag will also disable the Buildkit local cache."]}),"\n",(0,s.jsxs)(i.p,{children:["You can also disable Smart Builds by setting the environment variable ",(0,s.jsx)(i.code,{children:"OKTETO_SMART_BUILDS_ENABLED=false"}),".\nIf you define ",(0,s.jsx)(i.code,{children:"OKTETO_SMART_BUILDS_ENABLED=false"})," as an ",(0,s.jsx)(i.a,{href:"/docs/1.39/admin/dashboard#admin-variables",children:"Admin Variable"}),", Smart Builds is disabled for all the image builds for all developers in your organization.\nAdmin variables are equivalent to defining that variable on every developer's machine."]}),"\n","\n",(0,s.jsx)(i.h2,{id:"advanced-timeouts-configuration",children:"Advanced timeouts configuration"}),"\n",(0,s.jsxs)(i.p,{children:["The following environment variables can be useful for handling timeouts from the Okteto CLI when communicating with the Okteto Build Service.\nYou can configure them as ",(0,s.jsx)(i.a,{href:"/docs/1.39/admin/dashboard#admin-variables",children:"Admin Variables"})," if needed:"]}),"\n",(0,s.jsxs)(i.ul,{children:["\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.code,{children:"OKTETO_KEEPALIVE_CLIENT_TIME_MS"}),": After this duration of time, if the client doesn't see any activity it will ping the server to see if the transport is still alive. If set below 10s, a minimum value of 10s will be used (default value is infinity.)"]}),"\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.code,{children:"OKTETO_KEEPALIVE_CLIENT_TIMEOUT_MS"}),": After sending a keepalive ping, the client waits for this duration of time and if no activity is seen even after that the connection is closed. (default value is 20 seconds.)"]}),"\n",(0,s.jsxs)(i.li,{children:[(0,s.jsx)(i.code,{children:"OKTETO_KEEPALIVE_CLIENT_PERMIT_WITHOUT_STREAM"}),": If ",(0,s.jsx)(i.code,{children:"true"}),", the client sends keepalive pings even with no active RPCs. If ",(0,s.jsx)(i.code,{children:"false"}),", when there are no active RPCs, Time and Timeout will be ignored and no keepalive pings will be sent (defaults to ",(0,s.jsx)(i.code,{children:"false"}),".)"]}),"\n"]})]})}function u(e={}){const{wrapper:i}={...(0,a.R)(),...e.components};return i?(0,s.jsx)(i,{...e,children:(0,s.jsx)(h,{...e})}):h(e)}},98710:(e,i,t)=>{"use strict";t.d(i,{A:()=>n});const n=t.p+"assets/images/smart-builds-hash-248773177869bc3a2278851cc112769e.png"}}]);