1"use strict";(self.webpackChunkcivo_documentation=self.webpackChunkcivo_documentation||[]).push([[7267],{218:(e,n,i)=>{i.d(n,{A:()=>a});const a=i.p+"assets/images/create-instance-29c8f24d899e02c0e1a6947a08c4278c.png"},1470:(e,n,i)=>{i.d(n,{A:()=>k});var a=i(6540),t=i(8215),s=i(7559),o=i(3104),r=i(6347),c=i(205),l=i(7485),d=i(1682),h=i(9466);function u(e){return a.Children.toArray(e).filter((e=>"\n"!==e)).map((e=>{if(!e||(0,a.isValidElement)(e)&&function(e){const{props:n}=e;return!!n&&"object"==typeof n&&"value"in n}(e))return e;throw new Error(`Docusaurus error: Bad <Tabs> child <${"string"==typeof e.type?e.type:e.type.name}>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`)}))?.filter(Boolean)??[]}function p(e){const{values:n,children:i}=e;return(0,a.useMemo)((()=>{const e=n??function(e){return u(e).map((({props:{value:e,label:n,attributes:i,default:a}})=>({value:e,label:n,attributes:i,default:a})))}(i);return function(e){const n=(0,d.XI)(e,((e,n)=>e.value===n.value));if(n.length>0)throw new Error(`Docusaurus error: Duplicate values "${n.map((e=>e.value)).join(", ")}" found in <Tabs>. Every value needs to be unique.`)}(e),e}),[n,i])}function m({value:e,tabValues:n}){return n.some((n=>n.value===e))}function f({queryString:e=!1,groupId:n}){const i=(0,r.W6)(),t=function({queryString:e=!1,groupId:n}){if("string"==typeof e)return e;if(!1===e)return null;if(!0===e&&!n)throw new Error('Docusaurus error: The <Tabs> component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".');return n??null}({queryString:e,groupId:n});return[(0,l.aZ)(t),(0,a.useCallback)((e=>{if(!t)return;const n=new URLSearchParams(i.location.search);n.set(t,e),i.replace({...i.location,search:n.toString()})}),[t,i])]}function g(e){const{defaultValue:n,queryString:i=!1,groupId:t}=e,s=p(e),[o,r]=(0,a.useState)((()=>function({defaultValue:e,tabValues:n}){if(0===n.length)throw new Error("Docusaurus error: the <Tabs> component requires at least one <TabItem> children component");if(e){if(!m({value:e,tabValues:n}))throw new Error(`Docusaurus error: The <Tabs> has a defaultValue "${e}" but none of its children has the corresponding value. Available values are: ${n.map((e=>e.value)).join(", ")}. If you intend to show no default tab, use defaultValue={null} instead.`);return e}const i=n.find((e=>e.default))??n[0];if(!i)throw new Error("Unexpected error: 0 tabValues");return i.value}({defaultValue:n,tabValues:s}))),[l,d]=f({queryString:i,groupId:t}),[u,g]=function({groupId:e}){const n=function(e){return e?`docusaurus.tab.${e}`:null}(e),[i,t]=(0,h.Dv)(n);return[i,(0,a.useCallback)((e=>{n&&t.set(e)}),[n,t])]}({groupId:t}),v=(()=>{const e=l??u;return m({value:e,tabValues:s})?e:null})();(0,c.A)((()=>{v&&r(v)}),[v]);return{selectedValue:o,selectValue:(0,a.useCallback)((e=>{if(!m({value:e,tabValues:s}))throw new Error(`Can't select invalid tab value=${e}`);r(e),d(e),g(e)}),[d,g,s]),tabValues:s}}var v=i(2303);const y={tabList:"tabList__CuJ",tabItem:"tabItem_LNqP"};var b=i(4848);function w({className:e,block:n,selectedValue:i,selectValue:a,tabValues:s}){const r=[],{blockElementScrollPositionUntilNextRender:c}=(0,o.a_)(),l=e=>{const n=e.currentTarget,t=r.indexOf(n),o=s[t].value;o!==i&&(c(n),a(o))},d=e=>{let n=null;switch(e.key){case"Enter":l(e);break;case"ArrowRight":{const i=r.indexOf(e.currentTarget)+1;n=r[i]??r[0];break}case"ArrowLeft":{const i=r.indexOf(e.currentTarget)-1;n=r[i]??r[r.length-1];break}}n?.focus()};return(0,b.jsx)("ul",{role:"tablist","aria-orientation":"horizontal",className:(0,t.A)("tabs",{"tabs--block":n},e),children:s.map((({value:e,label:n,attributes:a})=>(0,b.jsx)("li",{role:"tab",tabIndex:i===e?0:-1,"aria-selected":i===e,ref:e=>{r.push(e)},onKeyDown:d,onClick:l,...a,className:(0,t.A)("tabs__item",y.tabItem,a?.className,{"tabs__item--active":i===e}),children:n??e},e)))})}function x({lazy:e,children:n,selectedValue:i}){const s=(Array.isArray(n)?n:[n]).filter(Boolean);if(e){const e=s.find((e=>e.props.value===i));return e?(0,a.cloneElement)(e,{className:(0,t.A)("margin-top--md",e.props.className)}):null}return(0,b.jsx)("div",{className:"margin-top--md",children:s.map(((e,n)=>(0,a.cloneElement)(e,{key:n,hidden:e.props.value!==i})))})}function j(e){const n=g(e);return(0,b.jsxs)("div",{className:(0,t.A)(s.G.tabs.container,"tabs-container",y.tabList),
1children:[(0,b.jsx)(w,{...n,...e}),(0,b.jsx)(x,{...n,...e})]})}function k(e){const n=(0,v.A)();return(0,b.jsx)(j,{...e,children:u(e.children)},String(n))}},3663:(e,n,i)=>{i.d(n,{A:()=>a});const a=i.p+"assets/images/terraform-instance-created-b151e99b74437dadd0ffbc82407c9ac8.png"},7819:(e,n,i)=>{i.d(n,{A:()=>a});const a=i.p+"assets/images/region-select-b1781add142f548eb1eb71e2e3743f5d.png"},8009:(e,n,i)=>{i.d(n,{A:()=>a});const a=i.p+"assets/images/instance-sizes-gpu-f0d04526639117bca1f1f4e0339b29e1.png"},8453:(e,n,i)=>{i.d(n,{R:()=>o,x:()=>r});var a=i(6540);const t={},s=a.createContext(t);function o(e){const n=a.useContext(s);return a.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:o(e.components),a.createElement(s.Provider,{value:n},e.children)}},8940:(e,n,i)=>{i.d(n,{A:()=>a});const a=i.p+"assets/images/instance-sizes-standard-b9f1bd99cb648cfaa9a29949df89da7f.png"},9365:(e,n,i)=>{i.d(n,{A:()=>o});i(6540);var a=i(8215);const t={tabItem:"tabItem_Ymn6"};var s=i(4848);function o({children:e,hidden:n,className:i}){return(0,s.jsx)("div",{role:"tabpanel",className:(0,a.A)(t.tabItem,i),hidden:n,children:e})}},9855:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>d,contentTitle:()=>l,default:()=>p,frontMatter:()=>c,metadata:()=>a,toc:()=>h});const a=JSON.parse('{"id":"compute/create-an-instance","title":"Creating an instance","description":"Learn how to easily create a customized Civo Compute instance that meets your specific needs using our Civo Dashboard, CLI or Terraform.","source":"@site/content/docs/compute/create-an-instance.md","sourceDirName":"compute","slug":"/compute/create-an-instance","permalink":"/docs/compute/create-an-instance","draft":false,"unlisted":false,"editUrl":"https://git.civo.com/civo/compute/public-docs/-/edit/main/content/docs/compute/create-an-instance.md","tags":[],"version":"current","lastUpdatedAt":null,"sidebarPosition":1,"frontMatter":{"sidebar_position":1,"title":"Creating an instance","description":"Learn how to easily create a customized Civo Compute instance that meets your specific needs using our Civo Dashboard, CLI or Terraform."},"sidebar":"mainSidebar","previous":{"title":"Compute","permalink":"/docs/compute/"},"next":{"title":"GPU instances","permalink":"/docs/compute/gpu-instances"}}');var t=i(4848),s=i(8453),o=i(1470),r=i(9365);const c={sidebar_position:1,title:"Creating an instance",description:"Learn how to easily create a customized Civo Compute instance that meets your specific needs using our Civo Dashboard, CLI or Terraform."},l=void 0,d={},h=[{value:"Overview",id:"overview",level:2},{value:"Creating an Instance for GPU Workloads on Civo",id:"creating-an-instance-for-gpu-workloads-on-civo",level:2},{value:"Creating a Standard Instance from the Civo Dashboard",id:"creating-a-standard-instance-from-the-civo-dashboard",level:2},{value:"1. Hostname",id:"1-hostname",level:3},{value:"2. How many instances?",id:"2-how-many-instances",level:3},{value:"3. Select size",id:"3-select-size",level:3},{value:"4. Select image",id:"4-select-image",level:3},{value:"5. Initial user",id:"5-initial-user",level:3},{value:"6. Network",id:"6-network",level:3},{value:"7. Public IP address",id:"7-public-ip-address",level:3},{value:"8. Firewall",id:"8-firewall",level:3},{value:"9. SSH Key",id:"9-ssh-key",level:3},{value:"10. Initialisation script",id:"10-initialisation-script",level:3},{value:"11. Tags",id:"11-tags",level:3},{value:"Creating your instance",id:"creating-your-instance",level:3},{value:"Accessing your instance with SSH",id:"accessing-your-instance-with-ssh",level:3},{value:"Creating an instance using the Civo CLI",id:"creating-an-instance-using-the-civo-cli",level:2},{value:"Creating an instance on the command line with no options",id:"creating-an-instance-on-the-command-line-with-no-options",level:3},{value:"Creating an instance on the command line with options",id:"creating-an-instance-on-the-command-line-with-options",level:3},{value:"Creating an instance using Terraform",id:"creating-an-instance-using-terraform",level:2},{value:"Preparing a configuration file",id:"preparing-a-configuration-file",level:3},{value:"Running Terraform plan",id:"running-terraform-plan",level:3},{value:"Applying the configuration",id:"applying-the-configuration",level:3},{value:"Updating an instance configuration",id:"updating-an-instance-configuration",level:3}];function u(e){const n={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",img:"img",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components},{Head:a}=n;return a||function(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Head",!0),(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(a,{children:(0,t.jsx)("title",{children:"Creating a Civo Compute Instance | Civo Documentation"})}),"\n","\n",(0,t.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,t.jsx)(n.p,{children:"To create an instance on Civo, you will need to provide several specific parameters. This requirement applies whether you are initiating the instance through the web dashboard or utilizing one of our API tools. In the sections below, you will find detailed documentation that explains the main options available to you during the initial launch of an instance. These options include various configuration settings that you can customize to suit your specific needs, ensuring that your instance is set up precisely as you require from the outset."}),"\n",(0,t.jsx)(n.h2,{id:"creating-an-instance-for-gpu-workloads-on-civo",children:"Creating an Instance for GPU Workloads on Civo"}),"\n",(0,t.jsx)(n.p,{children:"Civo offers the capability to run your GPU workloads on its specialized instances. The type of instance you select will differ based on the size and performance requirements you specify. This allows you to tailor your selection to meet a variety of performance needs, whether you are seeking low-latency responses for real-time applications, high-throughput for handling numerous inference requests, or other specific performance characteristics."}),"\n",(0,t.jsx)(n.p,{children:"With Civo, you have access to a comprehensive array of options designed to support and optimize your GPU workloads, ensuring you can achieve the desired performance and efficie
1ncy for your applications."}),"\n",(0,t.jsx)(n.p,{children:"Civo provides the following GPU Types:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"NVIDIA A100 40GB:"})," Designed for AI and data analytics, it delivers high performance and memory capacity."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"NVIDIA A100 80GB:"})," An enhanced version of the A100, offering more memory for demanding workloads such as large AI models."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"NVIDIA L40S 48GB:"})," Suitable for tasks requiring a mix of AI and graphics performance, such as 3D rendering and large language model training."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"NVIDIA H100:"})," Optimized for AI training and inference with advanced memory and Tensor Cores, suitable for high-performance computing and AI tasks."]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["To deploy GPU workloads on Civo Instances, ",(0,t.jsx)(n.a,{href:"#4-select-image",children:"select a GPU optimized image"})," from within the ",(0,t.jsx)(n.a,{href:"https://dashboard.civo.com/instances/new",children:"instance creation page"}),"."]}
1),"\n",(0,t.jsxs)(n.p,{children:["For an end-to-end walkthrough \u2014 including the Civo CUDA disk images and the single-GPU NVLink behaviour \u2014 see ",(0,t.jsx)(n.a,{href:"/docs/compute/gpu-instances",children:"GPU instances"}),"."]}),"\n",(0,t.jsxs)(o.A,{groupId:"create-instance",children:[(0,t.jsxs)(r.A,{value:"dashboard",label:"Dashboard",children:[(0,t.jsx)(n.h2,{id:"creating-a-standard-instance-from-the-civo-dashboard",children:"Creating a Standard Instance from the Civo Dashboard"}),(0,t.jsxs)(n.p,{children:["Begin by selecting the Civo Region you are operating in. You can do so in the lower left of your ",(0,t.jsx)(n.a,{href:"https://dashboard.civo.com",children:"Dashboard page"}),":"]}),(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"Region selection menu",src:i(7819).A+"",width:"188",height:"326"})}),(0,t.jsxs)(n.p,{children:["Then, navigate to the ",(0,t.jsx)(n.a,{href:"https://dashboard.civo.com/instances/new",children:"instance creation page"}),":"]}),(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"Instance creation page overview",src:i(218).A+"",width:"800",height:"918"})}),(0,t.jsx)(n.p,{children:"The numbered sections give you options for the specifications of your compute instances."}),(0,t.jsx)(n.h3,{id:"1-hostname",children:"1. Hostname"}),(0,t.jsxs)(n.p,{children:["The hostname is the name of the instance. If you specify multiple instances to create in section ",(0,t.jsx)(n.strong,{children:"2"})," the same hostname will be used for each, with a running sequential number added to make them unique."]}),(0,t.jsx)(n.p,{children:"Hostnames can only contain letters, numbers, dashes and full stops. Hostnames must end on an alphanumeric character, not a dash or full stop."}),(0,t.jsx)(n.h3,{id:"2-how-many-instances",children:"2. How many instances?"}),(0,t.jsxs)(n.p,{children:["You can create one or more instances in one operation, subject to the limitations of your ",(0,t.jsx)(n.a,{href:"/docs/account/quota",children:"quota"}),". Each instance created will have the same parameters, only the hostname and IP addresses will be different."]}),(0,t.jsx)(n.h3,{id:"3-select-size",children:"3. Select size"}),(0,t.jsxs)(n.p,{children:["You can select the size and instance hardware specifications based on the task you want to accomplish. You can view the available sizing options ",(0,t.jsx)(n.a,{href:"https://www.civo.com/pricing",children:"here"}),"."]}),(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"Compute instance sizes",src:i(8940).A+"",width:"1652",height:"1294"})}),(0,t.jsxs)(n.p,{children:["Some ",(0,t.jsx)(n.a,{href:"/docs/overview/regions",children:"Civo regions"})," provide the option to create instances with ",(0,t.jsx)(n.a,{href:"https://www.civo.com/ai/cloud-gpu",children:"attached GPUs"}),'. These can be selected on the corresponding "GPU" tabs of the sizes section, if available in your current region, as shown in the image below:']}),(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"GPU instance sizes",src:i(8009).A+"",width:"1724",height:"1574"})}),(0,t.jsxs)(n.p,{children:["Sizing options may be restricted depending on your account quota and how many resources are already running in your account. See the ",(0,t.jsx)(n.a,{href:"/docs/account/quota",children:"quota documentation"})," for more information."]}),(0,t.jsxs)(n.p,{children:["The hourly/monthly slider for the pricing is purely to show the pricing equivalent at different time scales. All Civo resources are billed hourly. ",(0,t.jsx)(n.a,{href:"/docs/account/billing",children:"Read more about billing"}),"."]}),(0,t.jsx)(n.admonition,{type:"tip",children:(0,t.jsx)(n.p,{children:"As the price charged increases with instance size, consider the type of work you expect the instance to be performing. If your instance is too small for the workload, it may not be able to remain responsive. If you over-budget the instance size, you may be paying more for the instance to mostly sit idle."})}),(0,t.jsx)(n.h3,{id:"4-select-image",children:"4. Select image"}),(0,t.jsx)(n.p,{children:"The base operating system image to use for the instance. Note that you can select from a number of versions of each operating system."}),(0,t.jsxs)(n.p,{children:["Custom operating system disk images can be enabled on ",(0,t.jsx)(n.a,{href:"https://www.civo.com/civostack-enterprise",children:"CivoStack Enterprise"})," regions. For more information on creating and managing custom disk images, refer to the ",(0,t.jsx)(n.a,{href:"/docs/compute/custom-image",children:"custom image"})," documentation."]}),(0,t.jsx)(n.h3,{id:"5-initial-user",children:"5. Initial user"}),(0,t.jsx)(n.p,{children:"The initial user to create for the created instance(s). This is the username to use when logging in to the instance for the first time over SSH."}),(0,t.jsx)(n.h3,{id:"6-network",children:"6. Network"}),(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.a,{href:"/docs/networking/private-networks",children:"private network"})," for the instance to be situated in. You can choose from the default network for your account, or if you have created networks prior to creating this instance, you can choose from one of them."]}),(0,t.jsx)(n.h3,{id:"7-public-ip-address",children:"7. Public IP address"}),(0,t.jsxs)(n.p,{children:["Select ",(0,t.jsx)(n.em,{children:"create"})," if you would want the instance to have a public IP address and therefore be routable from the wider internet. If you do not choose to create the instance with a public IP address, it will only be accessible from within your chosen ",(0,t.jsx)(n.a,{href:"/docs/networking/private-networks",children:"network"}),"."]}),(0,t.jsx)(n.h3,{id:"8-firewall",children:"8. Firewall"}),(0,t.jsx)(n.p,{children:"You can create a new firewall along with creating this instance, or choose from an existing one if present in the network. Read more about firewalls on Civo."}),(0,t.jsx)(n.h3,{id:"9-ssh-key",children:"9. SSH Key"}),(0,t.jsxs)(n.p,{children:["You can choose a random password for logging in to the instance, or use a ",(0,t.jsx)(n.a,{href:"/docs/account/ssh-keys",children:"previously-uploaded key"}),"."]}),(0,t.jsx)(n.h3,{id:"10-initialisation-script",children:"10. Initialisation script"}),(0,t.jsxs)(n.p,{children:["If you want your instance to be preinstalled with some tools, or want to run a script on startup, this is the section to paste the script. ",(0,t.jsx)(n.a,{href:"/docs/compute/install-script-usage",children:"Read more about instance initialisation script usage"}),"."]}),(0,t.jsx)(n.h3,{id:"11-tags",children:"11. Tags"}),(0,t.jsx)(n.p,{children:"You can tag instances for administrative and organisation reasons by adding tags here. Tags are entirely optional."}),(0,t.jsx)(n.h3,{id:"creating-your-instance",children:"Creating your instance"}),(0,t.jsxs)(n.p,{children:['When you are satisfied with your initial instance configuration, you can click "',(0,t.jsx)(n.strong,{children:"Create"}),"\" and be directed to the instance's dashboard page. It will take a moment to become active, and you will be shown the status throughout as it builds:"]}),(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"A Civo instance in the process of being built",src:i(9988).A+"",width:"2530",height:"660"})}),(0,t.jsx)(n.h3,{id:"accessing-your-instance-with-ssh",children:"Accessing your instance with SSH"}),(0,t.jsxs)(n.p,{children:["Once your instance is running, you will be able to connect to it using SSH. If you chose to use an ",(0,t.jsx)(n.a,{href:"/docs/account/ssh-keys",children:"uploaded SSH key"}),', you will be able to connect without a password. If you chose to use a random password, you can copy it to your clipboard by clicking on the "',(0,t.jsx)(n.em,{children:"View SSH information"})," dropdown at the top of the instance's page."]}),(0,t.jsxs)(n.p,{children:["Assuming you had a public IP address assigned to the instance, you will be able to access it with the command format ",(0,t.jsx)(n.code,{children:"ssh username@instanceIP"}
1),". The IP address information is also displayed at the top of the instance details page."]})]}),(0,t.jsxs)(r.A,{value:"cli",label:"Civo CLI",children:[(0,t.jsx)(n.h2,{id:"creating-an-instance-using-the-civo-cli",children:"Creating an instance using the Civo CLI"}),(0,t.jsxs)(n.p,{children:["You can create a Civo instance on the command-line by running the ",(0,t.jsx)(n.code,{children:"civo instance create"})," command, with optional parameters."]}),(0,t.jsxs)(n.admonition,{type:"tip",children:[(0,t.jsx)(n.p,{children:"You can view the instance creation options available on the Civo CLI by running:"}),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"civo instance create --help\n"})})]}),(0,t.jsx)(n.h3,{id:"creating-an-instance-on-the-command-line-with-no-options",children:"Creating an instance on the command line with no options"}),(0,t.jsxs)(n.p,{children:["If you run ",(0,t.jsx)(n.code,{children:"civo instance create"})," on its own, it will create an instance with a random name, default options for the size, operating system, initial user and so on, in the currently-selected region, and return."]}),(0,t.jsx)(n.h3,{id:"creating-an-instance-on-the-command-line-with-options",children:"Creating an instance on the command line with options"}),(0,t.jsxs)(n.p,{children:["The CLI allows you to specify a number of options for your instance, from the size and specification of the virtual machine, to the firewall rules to set up, the version and flavour of operating system to use, and more. A full list of options for instance creation can be found by running ",(0,t.jsx)(n.code,{children:"civo instance create --help"}),"."]}),(0,t.jsxs)(n.p,{children:["As an example, the following command will create an instance in the current region, using the ",(0,t.jsx)(n.code,{children:"g3.small"})," instance type, using the Ubuntu Jammy disk image for the operating system, with an initial user called demo-user."]}),(0,t.jsx)(n.p,{children:(0,t.jsx)(n.code,{children:"civo instance create --hostname=api-demo.test --size=g3.medium --diskimage=ubuntu-jammy --initialuser=demo-user"})})]}),(0,t.jsxs)(r.A,{value:"terraform",label:"Terraform",children:[(0,t.jsx)(n.h2,{id:"creating-an-instance-using-terraform",children:"Creating an instance using Terraform"}),(0,t.jsxs)(n.p,{children:["To create an instance using Terraform, you will first need to have an initialized Terraform project. Refer to the ",(0,t.jsx)(n.a,{href:"/docs/overview/terraform",children:"Civo Terraform setup documentation"})," before proceeding."]}),(0,t.jsx)(n.h3,{id:"preparing-a-configuration-file",children:"Preparing a configuration file"}),(0,t.jsxs)(n.p,{children:["First, create a file called ",(0,t.jsx)(n.code,{children:"main.tf"}),", and add the following Terraform code to it:"]}),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-terraform",children:'# Query small instance size\ndata "civo_size" "small" {\n filter {\n key = "name"\n values = ["g3.small"]\n match_by = "re"\n }\n\n filter {\n key = "type"\n values = ["instance"]\n }\n\n}\n\n# Query instance disk image\ndata "civo_disk_image" "debian" {\n region = "LON1"\n filter {\n key = "name"\n values = ["debian-10"]\n }\n}\n\n# Create a new instance\nresource "civo_instance" "foo" {\n region = "LON1"\n hostname = "foo.com"\n size = element(data.civo_
1size.small.sizes, 0).name\n disk_image = element(data.civo_disk_image.debian.diskimages, 0).id\n}\n'})}),(0,t.jsx)(n.p,{children:"To explain the contents of the file and what happens when the configuration above is applied:"}),(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["In the ",(0,t.jsx)(n.em,{children:"Query small instance size"})," block:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["We are using the ",(0,t.jsx)(n.code,{children:"civo_instances_size"})," data source to find a list of instance sizes that match with these filters:","\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["name contains ",(0,t.jsx)(n.code,{children:"g3.small"})]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"type"})," is ",(0,t.jsx)(n.code,{children:"instance"})]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["We can then refer to this data source as ",(0,t.jsx)(n.code,{children:"data.civo_instances_size.small"}),". To access the sizes later, we can use ",(0,t.jsx)(n.code,{children:"data.civo_instances_size.small.sizes"})," syntax where ",(0,t.jsx)(n.code,{children:"sizes"})," is the data source key that contains all the sizes (list)"]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:["In the ",(0,t.jsx)(n.em,{children:"Query instance disk image"})," block:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["We are using the ",(0,t.jsx)(n.code,{children:"civo_disk_image"})," data source to find a list of compute instance diski mages from the ",(0,t.jsx)(n.code,{children:"LON1"})," region that match this filter:","\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["name is ",(0,t.jsx)(n.code,{children:"debian-10"})]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["We can then refer to this data source as ",(0,t.jsx)(n.code,{children:"data.civo_disk_image.debian"}),". To access the sizes later, we can use ",(0,t.jsx)(n.code,{children:"data.civo_disk_image.debian.diskimages"})," syntax where ",(0,t.jsx)(n.code,{children:"diskimages"})," is the data source key that contains all the diskimages (list)"]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"In the Create a new instance block:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["We are creating a new Civo compute instance using the ",(0,t.jsx)(n.code,{children:"civo_instance"})," resource, and","\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Use ",(0,t.jsx)(n.code,{children:"LON1"})," region (note: this region field is optional \u2014 if no region is provided in the configuration or provider.tf file, the system will choose one for you)"]}),"\n",(0,t.jsxs)(n.li,{children:["Set the hostname to ",(0,t.jsx)(n.code,{children:"foo.com"})]}),"\n",(0,t.jsxs)(n.li,{children:["For the ",(0,t.jsx)(n.code,{children:"size"})," field, we take the first element (index 0) from the ",(0,t.jsx)(n.code,{children:"data.civo_instances_size.small.sizes"})," list defined above"]}),"\n",(0,t.jsxs)(n.li,{children:["For the ",(0,t.jsx)(n.code,{children:"disk_image"})," field, we take the first element (index 0) from the ",(0,t.jsx)(n.code,{children:"data.civo_disk_image.debian.diskimages"})," list"]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["We can then refer to this instance as ",(0,t.jsx)(n.code,{children:"civo_instance.foo"})," in other resources if we need to."]}),"\n"]}),"\n"]}),"\n"]}),(0,t.jsxs)(n.p,{children:["The civo_instance resource does support other fields too. Check out the ",(0,t.jsx)(n.a,{href:"https://registry.terraform.io/providers/civo/civo/latest/docs/resources/instance",children:"Terraform provider documentation"})," for more details."]}),(0,t.jsx)(n.h3,{id:"running-terraform-plan",children:"Running Terraform plan"}),(0,t.jsxs)(n.p,{children:["Once you have created the ",(0,t.jsx)(n.code,{children:"main.tf"})," file with your chosen options, you can run ",(0,t.jsx)(n.code,{children:"terraform plan"})," to see what's going to be created:"]}),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-console",children:'$ terraform plan\nTerraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:\n + create\n\nTerraform will perform the following actions:\n\n # civo_instance.foo will be created\n + resource "civo_instance" "foo" {\n + cpu_cores = (known after apply)\n + created_at = (known after apply)\n + disk_gb = (known after apply)\n + disk_image = "a4204155-a876-43fa-b4d6-ea2af8774560"\n + firewall_id = (known after apply)\n + hostname = "foo.com"\n + id = (known after apply)\n + initial_password = (sensitive value)\n + initial_user = "civo"\n + network_id = (known after apply)\n + private_ip = (known after apply)\n + pseudo_ip = (known after apply)\n + public_ip = (known after apply)\n + public_ip_required = "create"\n + ram_mb = (known after apply)\n + region = "LON1"\n + size = "g3.small"\n + source_id = (known after apply)\n + source_type = (known after apply)\n + status = (known after apply)\n + template = (known after apply)\n }\n\nPlan: 1 to add, 0 to change, 0 to destroy.\n\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nNote: You didn\'t use the -out option to save this plan, so Terraform can\'t guarantee to take exactly these actions if you run "terraform apply" now.\n'})}),(0,t.jsxs)(n.p,{children:["As you can see, Terraform will create an instance with size set to ",(0,t.jsx)(n.code,{children:"g3.small"})," and disk image set to ",(0,t.jsx)(n.code,{children:"a42...560"}),". That means the data source queries are working."]}),(0,t.jsx)(n.h3,{id:"applying-the-configuration",children:"Applying the configuration"}),(0,t.jsxs)(n.p,{children:["You can now execute the command to create the actual compute instance. Run ",(0,t.jsx)(n.code,{children:"terraform apply"})," and when prompted, type ",(0,t.jsx)(n.code,{children:"yes"}),":"]}),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-console",children:'$ terraform apply\nTerraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:\n + create\n\nTerraform will perform the following actions:\n\n # civo_instance.foo will be created\n + resource "civo_instance" "foo" {\n + cpu_cores = (known after apply)\n + created_at = (known after apply)\n + disk_gb = (known after apply)\n + disk_image = "a4204155-a876-43fa-b4d6-ea2af8774560"\n + firewall_id = (known after apply)\n + hostname = "foo.com"\n + id = (known after apply)\n + initial_password = (sensitive value)\n + initial_user = "civo"\n + network_id = (known after apply)\n + private_ip = (known after apply)\n + pseudo_ip = (known after apply)\n + public_ip = (known after apply)\n + public_ip_required = "create"\n + ram_mb = (known after apply)\n + region = "LON1"\n + size = "g3.small"\n + source_id = (known after apply)\n + source_type = (known after apply)\n + status = (known after apply)\n + template = (known after apply)\n }\n\nPlan: 1 to add, 0 to change, 0 to destroy.\n\nDo you want to perform these actions?\n Terraform will perform the actions described above.\n Only \'yes\' will be accepted to approve.\n\n Enter a value: yes\n\ncivo_instance.foo: Creating...\ncivo_instance.foo: Still creating... [10s elapsed]\ncivo_instance.foo: Still creating... [20s elapsed]\ncivo_instance.foo: Still creating... [30s elapsed]\ncivo_instance.foo: Still creating... [40s elapsed]\ncivo_instance.foo: Still creating... [50s elapsed]\ncivo_instance.foo: Still creating... [1m0s elapsed]\ncivo_instance.foo: Creation complete after 1m7s [id=689e385b-9b0a-4128-92b9-dae3b2ff95d3]\n\nApply complete! Resources: 1 added, 0 changed, 0 destroyed.\n'})}),(0,t.jsxs)(n.p,{children:["When the creation completes, refresh your ",(0,t.jsx)(n.a,{href:"https://dashboard.civo.com/instances",children:"Civo dashboard"})," and you will see there's a new compute instance that has been created. Click it to see more details. It will look something like this:"]}),(0,t.jsx)(n.p,{children:(0,t.jsx)(n.img,{alt:"Instance created from Terraform appears on the dashboard",src:i(3663).A+"",width:"941",height:"500"})}),(0,t.jsx)(n.h3,{id:"updating-an-instance-configuration",children:"Updating an instance configuration"}),(0,t.jsxs)(n.p,{children:["There will be a new file named ",(0,t.jsx)(n.code,{children:"terraform.tfstate"})," in your local project directory. If you print its contents, it will look something like:"]}
1),(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-console",children:'$ cat terraform.tfstate\n\n{\n "version": 4,\n "terraform_version": "1.1.7",\n "serial": 1,\n "lineage": "c59a555f-fbe1-857c-7a43-eee99902c716",\n "outputs": {},\n "resources": [\n {\n "mode": "data",\n "type": "civo_disk_image",\n "name": "debian",\n "provider": "provider[\\"registry.terraform.io/civo/civo\\"]",\n "instances": [\n {\n "schema_version": 0,\n "attributes": {\n "diskimages": [\n {\n "id": "a4204155-a876-43fa-b4d6-ea2af8774560",\n "label": "buster",\n "name": "debian-10",\n "version": "10"\n }\n ],\n "filter": [\n {\n "all": false,\n "key": "name",\n "match_by": "exact",\n "values": [\n "debian-10"\n ]\n }\n ],\n "id": "terraform-20220405065821786700000002",\n "region": "LON1",\n "sort": null\n },\n "sensitive_attributes": []\n }\n ]\n },\n {\n "mode": "data",\n "type": "civo_size",\n "name": "small",\n "provider": "provider[\\"registry.terraform.io/civo/civo\\"]",\n "instances": [\n {\n "schema_version": 0,\n "attributes": {\n "filter": [\n {\n "all": false,\n "key": "name",\n "match_by": "re",\n "values": [\n "g3.small"\n ]\n },\n {\n "all": false,\n "key": "type",\n "match_by": "exact",\n "values": [\n "instance"\n ]\n }\n ],\n "id": "terraform-20220405065821738300000001",\n "sizes": [\n {\n "cpu": 1,\n "description": "Small",\n "disk": 25,\n "name": "g3.small",\n "ram": 2048,\n "selectable": true,\n "type": "instance"\n }\n ],\n "sort": null\n },\n "sensitive_attributes": []\n }\n ]\n },\n {\n "mode": "managed",\n "type": "civo_instance",\n "name": "foo",\n "provider": "provider[\\"registry.terraform.io/civo/civo\\"]",\n "instances": [\n {\n "schema_version": 0,\n "attributes": {\n "cpu_cores": 1,\n "created_at": "2022-04-05 06:58:26 +0000 UTC",\n "disk_gb": 25,\n "disk_image": "a4204155-a876-43fa-b4d6-ea2af8774560",\n "firewall_id": "c9e14ae8-b8eb-4bae-a687-9da4637233da",\n "hostname": "foo.com",\n "id": "3ee28533-4914-491f-89ba-66b0c8fdbf8c",\n "initial_password": "2nXfV8M5FV",\n "initial_user": "civo",\n "network_id": "28244c7d-b1b9-48cf-9727-aebb3493aaac",\n "notes": "",\n "private_ip": "192.168.1.6",\n "public_ip": "74.220.16.89",\n "public_ip_required": "create",\n "ram_mb": 2048,\n "region": "LON1",\n "reverse_dns": "",\n "script": "",\n "size": "g3.small",\n "source_id": "debian-10",\n "source_type": "diskimage",\n "sshkey_id": "",\n "status": "ACTIVE",\n "tags": null,\n "template": null,\n "timeouts": null\n },\n "sensitive_attributes": [],\n "private": "eyJlMmJmYjczMC1lY2FhLTExZTYtOGY4OC0zNDM2M2JjN2M0YzAiOnsiY3JlYXRlIjoxODAwMDAwMDAwMDAwfX0=",\n "dependencies": [\n "data.civo_disk_image.debian",\n "data.civo_size.small"\n ]\n }\n ]\n }\n ]\n}\n'})}),(0,t.jsxs)(n.p,{children:["This is the ",(0,t.jsx)(n.a,{href:"https://developer.hashicorp.com/terraform/language/state",children:"Terraform State File"})," which is created when the configuration is applied."]}),(0,t.jsxs)(n.p,{children:["If you update your ",(0,t.jsx)(n.code,{children:"main.tf"})," file and run ",(0,t.jsx)(n.code,{children:"terraform apply"})," again, Terraform will refresh the state file, try to understand what you want to update and update your compute instance accordingly. You may want to update components such as the firewall id to choose another ",(0,t.jsx)(n.a,{href:"/docs/networking/firewalls",children:"firewall"})," or add a tag, for example."]}),(0,t.jsxs)(n.p,{children:["If there's no change in your ",(0,t.jsx)(n.code,{children:"main.tf"}
1)," file and you rerun ",(0,t.jsx)(n.code,{children:"terraform apply"}),", it will output a ",(0,t.jsx)(n.code,{children:"No changes. Your infrastructure matches the configuration"})," message back to you."]})]})]})]})}function p(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(u,{...e})}):u(e)}},9988:(e,n,i)=>{i.d(n,{A:()=>a});const a=i.p+"assets/images/instance-building-dfe74774527b0bf800fb1c70192b0727.png"}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.